Trae IDE Skills 嵌套目录解决方案

使用 Symbolic Link 解决 Trae IDE 无法发现嵌套目录中 Skills 的问题

问题背景

Trae 的 Skills 发现机制

Trae IDE 在启动时会扫描 ~/.trae/skills/ 目录（中文版为 ~/.trae-cn/skills/），查找直接子目录中的 SKILL.md 文件：

~/.trae/skills/
├── skill-a/SKILL.md           ✓ 会被发现（一级子目录）
├── skill-b/SKILL.md           ✓ 会被发现（一级子目录）
└── some-folder/
    └── nested/SKILL.md        ✗ 不会被发现（二级嵌套）

关键规则：Trae 只扫描一级子目录，不会递归扫描嵌套目录。

常见的目录结构冲突

许多优秀的 Skills 仓库采用如下结构：

some-skills-repo/
├── skills/                    <- Skills 在子目录中
│   ├── skill-a/SKILL.md
│   ├── skill-b/SKILL.md
│   └── ...
├── README.md
├── docs/
└── ...

问题：Skills 位于 repo/skills/ 子目录中，Trae 无法直接发现它们。

❌ 错误方案（不工作）

创建一个符号链接指向整个 skills 目录：

# ❌ 这个方案不工作！
ln -s ~/.trae/superpowers/skills ~/.trae/skills/superpowers

结果：

~/.trae/skills/
├── superpowers/              <- 符号链接（容器目录）
│   ├── brainstorming/SKILL.md   ✗ 二级嵌套，不会被发现
│   ├── writing-plans/SKILL.md   ✗ 二级嵌套，不会被发现
│   └── ...

为什么不行：Trae 只扫描一级子目录，superpowers/brainstorming/SKILL.md 是二级嵌套！

✅ 正确方案：为每个 Skill 创建单独的链接

方案一：使用脚本批量创建（推荐）

Windows (PowerShell)

注意：Windows 创建 Symbolic Link 需要管理员权限。请以管理员身份运行 PowerShell。

# 定义 skills 列表
$skills = @(
    "brainstorming",
    "dispatching-parallel-agents",
    "executing-plans",
    "finishing-a-development-branch",
    "receiving-code-review",
    "requesting-code-review",
    "subagent-driven-development",
    "systematic-debugging",
    "test-driven-development",
    "using-git-worktrees",
    "using-superpowers",
    "verification-before-completion",
    "writing-plans",
    "writing-skills"
)

# 为每个 skill 创建 Symbolic Link（需要管理员权限）
foreach ($skill in $skills) {
    $target = "$env:USERPROFILE\.trae-cn\skills\superpowers\skills\$skill"
    $link = "$env:USERPROFILE\.trae-cn\skills\$skill"
    
    if (-not (Test-Path $link)) {
        New-Item -ItemType SymbolicLink -Path $link -Target $target | Out-Null
        Write-Host "Created: $skill" -ForegroundColor Green
    } else {
        Write-Host "Exists: $skill" -ForegroundColor Yellow
    }
}
替代方案：使用 Junction（无需管理员权限）

如果无法获取管理员权限，可以使用 Junction 作为替代：

# Junction 不需要管理员权限
foreach ($skill in $skills) {
    $target = "$env:USERPROFILE\.trae-cn\skills\superpowers\skills\$skill"
    $link = "$env:USERPROFILE\.trae-cn\skills\$skill"
    
    if (-not (Test-Path $link)) {
        New-Item -ItemType Junction -Path $link -Target $target | Out-Null
        Write-Host "Created: $skill" -ForegroundColor Green
    }
}

Junction 与 Symbolic Link 的区别：

类型 权限要求 跨文件系统 兼容性
Symbolic Link 需要管理员权限 支持 最佳
Junction 普通用户即可 仅同一文件系统 Windows 专用
macOS / Linux
# 定义 skills 列表
skills=(
    "brainstorming"
    "dispatching-parallel-agents"
    "executing-plans"
    "finishing-a-development-branch"
    "receiving-code-review"
    "requesting-code-review"
    "subagent-driven-development"
    "systematic-debugging"
    "test-driven-development"
    "using-git-worktrees"
    "using-superpowers"
    "verification-before-completion"
    "writing-plans"
    "writing-skills"
)

# 为每个 skill 创建符号链接
for skill in "${skills[@]}"; do
    target="$HOME/.trae/skills/superpowers/skills/$skill"
    link="$HOME/.trae/skills/$skill"
    
    if [ ! -L "$link" ]; then
        ln -s "$target" "$link"
        echo "Created: $skill"
    else
        echo "Exists: $skill"
    fi
done

方案二：手动创建单个链接

Windows (PowerShell)
# 单个 skill 创建示例（需要管理员权限）
New-Item -ItemType SymbolicLink `
    -Path "$env:USERPROFILE\.trae-cn\skills\brainstorming" `
    -Target "$env:USERPROFILE\.trae-cn\skills\superpowers\skills\brainstorming"
macOS / Linux
# 单个 skill 创建示例
ln -s ~/.trae/skills/superpowers/skills/brainstorming ~/.trae/skills/brainstorming

最终目录结构

~/.trae-cn/skills/
│
├── superpowers/                    <- 仓库根目录
│   └── skills/                     <- 源 skills（实际文件）
│       ├── brainstorming/SKILL.md
│       ├── writing-plans/SKILL.md
│       └── ...
│
├── brainstorming/ ────────────────► superpowers/skills/brainstorming/
├── writing-plans/ ────────────────► superpowers/skills/writing-plans/
├── test-driven-development/ ──────► superpowers/skills/test-driven-development/
├── systematic-debugging/ ─────────► superpowers/skills/systematic-debugging/
├── subagent-driven-development/ ──► superpowers/skills/subagent-driven-development/
├── dispatching-parallel-agents/ ──► superpowers/skills/dispatching-parallel-agents/
├── executing-plans/ ──────────────► superpowers/skills/executing-plans/
├── verification-before-completion/ ► superpowers/skills/verification-before-completion/
├── requesting-code-review/ ───────► superpowers/skills/requesting-code-review/
├── receiving-code-review/ ────────► superpowers/skills/receiving-code-review/
├── using-git-worktrees/ ──────────► superpowers/skills/using-git-worktrees/
├── finishing-a-development-branch/ ► superpowers/skills/finishing-a-development-branch/
├── writing-skills/ ───────────────► superpowers/skills/writing-skills/
└── using-superpowers/ ────────────► superpowers/skills/using-superpowers/

关键点：每个 skill 都是 skills/ 目录下的直接子目录，Trae 可以正确发现！

工作原理

┌─────────────────────────────────────────────────────────────┐
│                     Trae IDE 启动                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              扫描 ~/.trae/skills/ 目录                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  发现直接子目录（一级）：                                     │
│  ├── brainstorming/SKILL.md      ✓ Symbolic Link            │
│  ├── writing-plans/SKILL.md      ✓ Symbolic Link            │
│  ├── test-driven-development/    ✓ Symbolic Link            │
│  └── ...                                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              解析 SKILL.md 的 frontmatter                    │
│              加载技能到内存                                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              技能准备就绪，等待触发                           │
└─────────────────────────────────────────────────────────────┘

安装指南

完整步骤

  1. 克隆仓库
  2. 为每个 skill 创建链接
  3. 重启 Trae IDE
  4. 验证安装

示例：以 Superpowers 为例

步骤 1：克隆仓库

macOS / Linux：

git clone https://github.com/obra/superpowers.git ~/.trae/superpowers

Windows (PowerShell)：

git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.trae-cn\superpowers"

中文版 Trae 用户：将 .trae 替换为 .trae-cn

步骤 2：创建链接

使用上面的脚本为每个 skill 创建链接。

步骤 3：重启 Trae IDE

关闭并重新打开 Trae IDE，让它重新扫描 skills 目录。

步骤 4：验证安装
# Windows - 检查所有 Symbolic Link
Get-ChildItem "$env:USERPROFILE\.trae-cn\skills" -Directory | 
    Where-Object { $_.LinkType -eq "SymbolicLink" } | 
    Select-Object Name

在 Trae 中开始新对话，尝试：

  • “使用头脑风暴 skill 来分析这个需求”
  • “帮我用 TDD 方式实现这个功能”

如果 Trae 能够识别并激活相应的技能，说明安装成功！

SKILL.md 格式

每个技能的 SKILL.md 文件包含 YAML frontmatter：

---
name: skill-name
description: Use when [触发条件] - [技能功能描述]
---

# Skill Name

[技能内容...]

Trae 通过 description 字段判断何时自动激活技能。

更新与维护

更新 Skills

由于使用了链接，更新仓库后立即生效：

macOS / Linux：

cd ~/.trae/superpowers && git pull

Windows (PowerShell)：

cd "$env:USERPROFILE\.trae-cn\superpowers"; git pull

卸载

删除所有 Symbolic Link：

Windows (PowerShell)：

$skills = @("brainstorming", "writing-plans", "test-driven-development", "systematic-debugging", "subagent-driven-development", "dispatching-parallel-agents", "executing-plans", "verification-before-completion", "requesting-code-review", "receiving-code-review", "using-git-worktrees", "finishing-a-development-branch", "writing-skills", "using-superpowers")

foreach ($skill in $skills) {
    $link = "$env:USERPROFILE\.trae-cn\skills\$skill"
    if (Test-Path $link) {
        Remove-Item $link -Force
        Write-Host "Removed: $skill"
    }
}

macOS / Linux：

rm ~/.trae/skills/brainstorming
rm ~/.trae/skills/writing-plans
# ... 删除其他链接

删除仓库（可选）：

rm -rf ~/.trae/superpowers

故障排除

技能未被发现

  1. 验证链接是否正确：

Windows：

Get-ChildItem "$env:USERPROFILE\.trae-cn\skills" -Directory | 
    Where-Object { $_.LinkType -eq "SymbolicLink" } | 
    Select-Object Name, Target

macOS / Linux：

ls -la ~/.trae/skills/
  1. 检查 SKILL.md 是否存在：
Test-Path "$env:USERPROFILE\.trae-cn\skills\brainstorming\SKILL.md"
  1. 重启 Trae IDE：技能在启动时被发现

中文版 Trae 路径

中文版 Trae 使用 .trae-cn 目录：

# 中文版路径
$env:USERPROFILE\.trae-cn\skills\
$env:USERPROFILE\.trae-cn\superpowers\

技能激活不正确

检查 SKILL.md 的 description 字段是否清晰描述了触发条件。

创建自定义技能

你可以在 ~/.trae/skills/ 中创建自己的技能：

mkdir -p ~/.trae/skills/my-custom-skill

创建 ~/.trae/skills/my-custom-skill/SKILL.md：

---
name: my-custom-skill
description: Use when [触发条件] - [技能功能描述]
---

# My Custom Skill

[你的技能内容...]

## 使用场景

- 场景 1
- 场景 2

## 工作流程

1. 步骤 1
2. 步骤 2

description 字段是 Trae 自动激活技能的关键，请清晰描述触发条件。

命令速查表

Windows (PowerShell)

# 克隆仓库
git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.trae-cn\superpowers"

# 批量创建 Symbolic Link（需要管理员权限）
$skills = @("brainstorming", "writing-plans", "test-driven-development", "systematic-debugging", "subagent-driven-development", "dispatching-parallel-agents", "executing-plans", "verification-before-completion", "requesting-code-review", "receiving-code-review", "using-git-worktrees", "finishing-a-development-branch", "writing-skills", "using-superpowers")
foreach ($skill in $skills) {
    New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.trae-cn\skills\$skill" -Target "$env:USERPROFILE\.trae-cn\superpowers\skills\$skill" -Force | Out-Null
}

# 验证链接
Get-ChildItem "$env:USERPROFILE\.trae-cn\skills" -Directory | Where-Object { $_.LinkType -eq "SymbolicLink" } | Select-Object Name

# 更新
cd "$env:USERPROFILE\.trae-cn\superpowers"; git pull

# 卸载（删除所有链接）
foreach ($skill in $skills) { Remove-Item "$env:USERPROFILE\.trae-cn\skills\$skill" -Force }
Windows 替代方案：Junction（无需管理员权限） 
# 批量创建 Junction（无需管理员权限）
foreach ($skill in $skills) {
    New-Item -ItemType Junction -Path "$env:USERPROFILE\.trae-cn\skills\$skill" -Target "$env:USERPROFILE\.trae-cn\superpowers\skills\$skill" -Force | Out-Null
}

# 验证 Junction
Get-ChildItem "$env:USERPROFILE\.trae-cn\skills" -Directory | Where-Object { $_.LinkType -eq "Junction" } | Select-Object Name

macOS / Linux

# 克隆仓库
git clone https://github.com/obra/superpowers.git ~/.trae/superpowers

# 批量创建符号链接
skills=("brainstorming" "writing-plans" "test-driven-development" "systematic-debugging" "subagent-driven-development" "dispatching-parallel-agents" "executing-plans" "verification-before-completion" "requesting-code-review" "receiving-code-review" "using-git-worktrees" "finishing-a-development-branch" "writing-skills" "using-superpowers")
for skill in "${skills[@]}"; do
    ln -s ~/.trae/superpowers/skills/$skill ~/.trae/skills/$skill
done

# 验证链接
ls -la ~/.trae/skills/

# 更新
cd ~/.trae/superpowers && git pull

# 卸载
for skill in "${skills[@]}"; do rm ~/.trae/skills/$skill; done
rm -rf ~/.trae/superpowers

相关资源

  • Trae 官网：https://www.trae.ai/
  • Trae 文档：https://docs.trae.ai/
  • Superpowers 仓库（示例）：https://github.com/obra/superpowers

总结

关键要点

  1. Trae 只扫描一级子目录 - 不会递归扫描嵌套目录
  2. 为每个 skill 创建单独的链接 - 不是创建一个容器链接
  3. 使用 Symbolic Link - 跨平台通用方案
  4. 链接后每个 skill 都是直接子目录 - Trae 可以正确发现

优点

  1. 无需修改仓库 - 不需要提交任何更改
  2. 自动更新 - git pull 后立即生效
  3. 原生支持 - 使用 Trae 标准的技能发现机制
  4. 通用方案 - 适用于任何嵌套目录的 Skills 仓库

祝你使用愉快！🚀

# ide
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

RAG 多模态文档处理：为什么直接 OCR 文本 chunk 会带偏 DeepSeek 问答结果

avatar DeepSeek技术社区
cover

提示词管理：从十几个YAML文件到版本控制的工程实践

avatar DeepSeek技术社区
cover

DeepSeek自动化评测实践：Golden Set构建与通过率漂移预警

avatar DeepSeek技术社区