Claude Code、Codex、dsh(DeepSeek Harness)、ZCode、pi、Qoder、OpenCode、WorkBuddy 与 TRAE 都采用「<skill-name>/SKILL.md 目录 bundle + frontmatter」的通用格式,因此一个 skill 本质上就是一个带说明文件的目录。a4agent 自 0.2.0 起内置技能管理,经 0.2.2(四端)、0.5.0(六端)、0.6.1(七端,新增 OpenCode)、0.6.3(八端,新增 WorkBuddy)到 0.7.2 扩展为九端(新增 TRAE):自动发现九端已有的全局级与项目级 skill,跨端迁移时非破坏复制(源端保留),目标端同名旧版先移入回收站再写入,并提供一键补齐九端、SKILL.md 预览、回收站与迁移日志。此外,任务下发可在下发时勾选技能并自动注入工作目录(0.6.6 起)。本文章介绍技能的发现机制、迁移与一键适配、回收站与迁移日志的追溯,以及项目来源的配置。

1. 九端 skill 的通用形态

九端 skill 都遵循同一个约定:一个以 skill 名命名的目录,内含一个 SKILL.md,开头用 frontmatter 声明 name 与 description,其后是正文(Markdown):

git-commit/
└── SKILL.md        # frontmatter:name / description + 正文
---
name: git-commit
description: "执行 git add、生成 Angular 规范 commit 消息、交由用户确认后 commit + push"
---

# 技能说明
正文内容……

a4agent 正是以 frontmatter 的 name 作为唯一标识做发现与冲突判定的:两个 skill「同名」指 frontmatter 的 name 相同或目录名相同,二者任一命中即视为冲突。

1.1 九端存放位置

端 全局根 项目级根
Claude Code ~/.claude/skills(可用 A4AGENT_CLAUDE_SKILLS_PATH 覆盖) <项目根>/.claude/skills
Codex ~/.codex/skills(可用 A4AGENT_CODEX_SKILLS_PATH 覆盖) <项目根>/.codex/skills
dsh ~/.dsh/skills($DSH_HOME / A4AGENT_DSH_SKILLS_PATH) <项目根>/.dsh/skills
ZCode ~/.zcode/skills(可用 A4AGENT_ZCODE_SKILLS_PATH 覆盖) <项目根>/.zcode/skills
pi ~/.pi/agent/skills($PI_CODING_AGENT_DIR / A4AGENT_PI_AGENT_DIR,注意是 agent 子目录) <项目根>/.pi/skills
Qoder ~/.qoder/skills(A4AGENT_QODER_HOME;国内版目录为 ~/.qoder-cn) <项目根>/.qoder/skills
OpenCode ~/.config/opencode/skills(A4AGENT_OPENCODE_SKILLS_PATH,注意不是 ~/.opencode/skills) <项目根>/.opencode/skills
WorkBuddy ~/.workbuddy/skills(可用 A4AGENT_WORKBUDDY_SKILLS_PATH 覆盖) <项目根>/.workbuddy/skills
TRAE ~/.trae-cn/skills(可用 A4AGENT_TRAE_SKILLS_PATH 覆盖) <项目根>/.trae/skills

几个端各有需要注意的地方:

ZCode:官方还识别跨工具兼容目录 ~/.agents/skills 与 <项目>/.agents/skills;a4agent 统一托管到 .zcode 前缀,与其它端保持一致,迁移到 ZCode 的 skill 会被 ZCode 客户端真实读取。

pi:全局技能在 agent 子目录下(~/.pi/agent/skills,不是 ~/.pi/skills)。pi 对 skill 的校验比其它端严格:name 只能是小写字母、数字与连字符(≤64 字符,不得以连字符开头结尾或含连续连字符),description 必填且 ≤1024 字符,不合规的 skill pi 会直接不加载。迁移到 pi 时 a4agent 会按 pi 的规则复查一次,不合规则在迁移结果里明确警告,而不是留下「迁成功却找不到」的状态。

Qoder:除 ~/.qoder/skills 外还识别跨工具目录 ~/.agents/skills 与 <项目>/.agents/skills(优先级低于前者),a4agent 统一托管到 .qoder/skills 前缀;项目级路径与其它端同为 .{tool}/skills,因此发现 / 迁移 / 自选文件夹三条路径都无需特判。配置目录名随发行版而变(国际版 .qoder、国内版 .qoder-cn),默认探测实际存在的那个。

OpenCode:技能 ID 取目录名,frontmatter 的 name 只是显示名,因此 a4agent 在 OpenCode 端按目录名聚合并判定冲突——否则两个「显示名相同、ID 不同」的技能会被错并成一份,或在迁移时被误删(它们在 OpenCode 里是两个各自工作的技能)。此外它会自动发现 ~/.claude/skills 与 ~/.agents/skills,这类条目会被标注「OpenCode 已可见」、「一键适配全部端」时跳过——不必为了 OpenCode 再迁一份。

WorkBuddy:0.6.3 起支持(社区贡献),路径走通用公式、无特殊校验规则,全局根在 ~/.workbuddy/skills,项目级与其它端同为 <项目根>/.workbuddy/skills,发现 / 迁移 / 自选文件夹三条路径都无需特判。

TRAE:0.7.2 起支持,全局根在 TRAE 产品数据目录下的 skills(本机即 ~/.trae-cn/skills),项目级 <项目根>/.trae/skills 正好命中 .{tool}/skills 通用公式、无需特判。唯一特例是 TRAE 的内置技能目录(~/.trae-cn/builtin/global/skills)——它会随 TRAE 更新流程整体重写,a4agent 不写入、不托管,列表里只出现你自己的技能。

项目根列表持久化在数据目录的 projects.json 中,用于扫描各项目下的项目级 skill。

2. 发现:聚合与重复标注

「技能管理」页签加载时调用 /skills/discover,扫描九端全部全局根与各项目的根,把跨端同名的 skill 聚合到一张卡片上,并标注「已在 N 端存在」:

graph LR A[扫描九端全局根] --> D[聚合 frontmatter name] B[扫描各项目的根] --> D D --> E{同名?} E -->|是| F[合并到一张卡片
标注「已在 N 端存在」] E -->|否| G[单独一张卡片] F --> H[渲染卡片列表] G --> H style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style F fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

几个细节:

  • 保留目录跳过:Codex 全局根下的 .system/ 及一切以点开头的目录视为系统保留目录,一律不扫描、不视为用户 skill。
  • 路径归属校验:卡片会记录每个副本的路径,供预览、打开、删除、迁移使用。
  • 重复标注:git-commit 若同时存在于 Claude 与 dsh,卡片上会显示两端徽章与紫色「2 端存在」徽章。
  • 端级冲突口径:绝大多数端以 frontmatter name 判定同名,OpenCode 例外——它按目录名判定(见 1.1),避免把两个各自可用的技能错并或被误删。

3. 迁移:非破坏复制

点击卡片的「迁移…」会在弹窗上半部分选择拥有的源副本,下半部分勾选目标位置(全局、各项目、各端组合),执行后把源目录复制到每个目标端。

graph LR A[选择源副本] --> B{目标端是否
已存在同名?} B -->|否| C[直接复制
源端保留] B -->|是| D[旧版先移入
回收站] D --> E[写入新版本] C --> F[写入迁移日志] E --> F style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style D fill:#ffecd6,stroke:#e67e22,stroke-width:2px style E fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
  • 源端永远保留:迁移是复制而非移动,源端目录原地不动。
  • 同名冲突保护:目标端已存在同名 skill 时,旧版先移入回收站再写入新内容,不静默覆盖(0.6.3 起写入改为 staging 暂存换入并跳过 junction / 链接,异常时按端回滚,用户可见语义不变)。
  • 每对迁移写日志:每一对「源 → 目标」迁移都会写入 SkillMigration 日志(新→旧排序),单对失败不影响其余对的执行。

3.1 迁移到自选项目文件夹(0.3.1 起)

迁移目标的「项目」不再限于已登记的项目根:迁移对话框新增自选项目文件夹,目标项目无需事先存在任何 skill(哪怕只有 Agent 工作记录),.{tool}/skills 目录缺失时自动逐级创建。

  • 桌面端直接调用系统原生目录选择框(pywebview),浏览器调试模式退化为手动输入路径;
  • 从自选路径迁出(作为源端)同样支持;
  • 与既有保护完全兼容:非法路径整体预校验拦截、源=目标自动跳过、同名旧版先入回收站。

3.2 一键适配全部端

在「项目视图」中,每个项目的块右上角有「一键适配全部端」按钮:先弹出一份计划清单(哪个 skill 缺哪几端),确认后按缺失端一次补齐,迁移过程带进度条并临时锁定页面其他操作。已齐全的项目点击则提示已在全部端齐全。

OpenCode 会自动发现 ~/.claude/skills 与 ~/.agents/skills,落在这两处的技能对 OpenCode 而言本来就可见,因此会被标注「OpenCode 已可见」并在补齐时跳过,不会白白多拷一份。适配范围 0.6.3 起计入 WorkBuddy、0.7.2 起计入 TRAE,补齐目标为全部九端。

graph LR A[选一个缺端项目] --> B[生成计划清单
skill → 缺哪几端] B --> C[执行补齐
带进度条] C --> D{目标端同名?} D -->|是| E[旧版入回收站] D -->|否| F[直接复制] E --> G[写入日志] F --> G G --> H[适配完成] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style C fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

4. 预览与打开

卡片上每个副本行悬停会出现「打开 / 删除」小链接:

  • 预览:调用 /skills/content 读取 SKILL.md 的 frontmatter 与正文,在弹窗顶部灰框显示描述与路径,下方渲染正文 Markdown;无正文时显示「SKILL.md 没有正文内容」占位。
  • 资源管理器打开:调用 /skills/open 在系统资源管理器中定位到该 skill 目录;越界路径(如 C:\Windows\System32)会被拒绝返回 400,不会打开资源管理器。

两点关于目录链接与特殊环境的保障(0.3.3 起):

  • junction / 软链接 skill 正常操作:把 skill 以目录联接形式放进工具全局目录(如 Codex 端指向仓库真实目录的链接)时,预览 / 打开 / 删除照常可用——操作前的归属校验采用不解析链接、不访问文件系统的纯字符串归一化,与发现流程同视角;删除只移走链接本身,链接指向的真实目录不受影响,回收站恢复后链接原样接回。
  • 不可访问目录不再拖垮整体:Windows 11 24H2 的「不受信任的装入点」会间歇性拒绝遍历部分链接目录(WinError 448),发现扫描对单个无法访问的目录记警告并跳过,不影响其余结果的返回。

5. 回收站

删除 skill(含同名迁移时落下的旧版)会移入回收站而非彻底删除,30 天内可恢复:

  • 原位记录:SkillTrash 表记录原路径、名称等信息,恢复时把目录放回原位置。
  • 惰性过期清理:回收站条目超过 30 天时在访问时惰性清理,顶部提示「已自动清理 N 条超过 30 天的过期条目」。
  • 恢复冲突拦截:若原位置已被同名目录占用,恢复会报错「原位置已存在同名目录」,且不覆盖手动目录。
  • 彻底删除:对单条目「彻底删除」会永久移除,磁盘上对应回收站目录同步消失;也可批量清理全部过期条目。
graph LR A[删除 skill] --> B[移入回收站
记录原位置] B --> C{30 天内?} C -->|是| D[可恢复原位
或彻底删除] C -->|否| E[惰性过期清理] D --> F[迁移日志可追溯] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style E fill:#fadbd8,stroke:#c0392b,stroke-width:2px style F fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px

6. 迁移日志

每次成功或失败的迁移都写入 SkillMigration 日志,包含时间、Skill、源、目标、结果,可在「迁移日志」弹窗中按新→旧查看。人为制造一次失败(如把目标项目目录改名后再迁移到它)也会以失败明细记录在案,便于追溯。

7. 项目来源配置

「技能管理」页签右侧的「项目来源」(0.6.4 前叫「项目根目录」)决定扫描哪些项目。0.6.4 起默认扫描本机所有可见盘符,并读取各工具自己留存的历史自动发现项目——Claude Code 项目表、Codex 会话工作目录、VS Code 最近工作区,任意深度的项目零配置出现;自动发现的线索带 10 分钟缓存,可用环境变量 A4AGENT_PROJECT_HINTS=0 关闭。

弹窗里可逐条忽略不需要的项目,也可恢复默认扫描范围;圈定与忽略的选择持久化到数据目录的 projects.json,项目视图据此分组展示。

8. 常见问题

问:迁移会把源端的 skill 移走吗?

答:不会。迁移是非破坏复制,源端目录原地保留,只在目标端写入副本;目标端同名旧版先进回收站而非直接覆盖。

问:目标端已经有同名 skill 了还能迁移吗?

答:可以,但旧版会被移入回收站(30 天内可恢复),新内容随后写入。这是为避免静默覆盖导致的能力退化。

问:想撤销一次误删除怎么办?

答:删除的 skill(含迁移落下的旧版)都进了回收站,在 30 天内到「回收站」选中对应条目点「恢复」即可放回原位置;若恢复时原位置已被占用会报错提示。

问:为什么 Codex 的某些 skill 没有出现在列表里?

答:Codex 全局根下的 .system/ 及一切以点开头的目录被视为系统保留目录,一律跳过,不视为用户 skill。pi 端同样会跳过 node_modules 与点开头的目录,并遵守 .gitignore / .ignore / .fdignore(被忽略的目录不会出现)。

问:迁移到 pi 之后在 pi 里找不到这个 skill?

答:pi 的校验比其它端严格:name 只能是小写字母、数字与连字符(≤64 字符,不得以连字符开头结尾或含连续连字符),description 必填且 ≤1024 字符,缺 description 的 bundle pi 直接不加载。迁移到 pi 时 a4agent 会复查一次,不合规则在迁移结果里给出警告——按提示补上 description 或改合规的目录名即可。

问:OpenCode 的技能为什么按目录名判定同名?

答:因为 OpenCode 的技能 ID 就是目录名,frontmatter 的 name 只是显示名。若按显示名判定,两个 ID 不同、各自可用的技能会被错并成一份,迁移时还可能被当作冲突误删。

问:ZCode 的 skill 放在哪里会被 a4agent 管理?

答:a4agent 统一托管到 ~/.zcode/skills(全局)与 <项目>/.zcode/skills(项目级),与其它端前缀一致(自 0.2.2 起)。ZCode 官方额外识别的 ~/.agents/skills 兼容目录既有内容不会被删除,但新迁移统一写入 .zcode 前缀。

问:以目录联接(junction)形式放的 skill 能正常预览和删除吗?

答:能(自 0.3.3 起)。归属校验不再解析链接,与发现流程同视角;删除只移走链接本身、不动链接指向的真实目录,从回收站恢复后链接原样接回。若该链接正被 Windows 11 24H2 防护临时拦截(不受信任的装入点),它会短暂从列表消失、放行后自动恢复,属预期行为。

问:迁移时想让目标项目不在项目根列表里怎么办?

答:用迁移对话框的「自选项目文件夹」(自 0.3.1 起)直接选择任意文件夹作为目标,.{tool}/skills 目录缺失时自动创建;作为源端迁出同样支持。

问:项目列表里出现了我没登记过的项目,怎么去掉?

答:0.6.4 起项目默认按盘符全盘扫描并从各工具历史自动发现,无需登记即可出现;在「项目来源」弹窗里把不需要的条目忽略即可,之后扫描会跳过它。

问:TRAE 的内置技能为什么不出现在列表里?

答:TRAE 自带的内置技能放在 ~/.trae-cn/builtin/global/skills,该目录会随 TRAE 更新整体重写,a4agent 不写入、不托管,列表里只出现你自己的全局与项目级技能。想给 TRAE 补技能,迁到全局根 ~/.trae-cn/skills 或项目级 .trae/skills 即可。

问:任务下发时勾选的技能是怎么进入目标端的?

答:0.6.6 起,下发与循环任务勾选的技能会在运行前自动注入工作目录的 .<端>/skills(Windows 目录联接优先、源不可用回退复制、同名跳过不覆盖、按引用计数回收)。机制细节见任务下发第 6 节。