Claude Code、Codex、dsh（DeepSeek Harness）与 ZCode 都采用「<skill-name>/SKILL.md 目录 bundle + frontmatter」的四端通用格式，因此一个 skill 本质上就是一个带说明文件的目录。a4api 自 0.2.0 起内置技能管理，0.2.2 起扩展为四端：自动发现四端已有的全局级与项目级 skill，跨端迁移时非破坏复制（源端保留），目标端同名旧版先移入回收站再写入，并提供一键补齐四端、SKILL.md 预览、回收站与迁移日志。本文章介绍技能的发现机制、迁移与一键适配、回收站与迁移日志的追溯，以及项目根目录的配置。

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"
---

# 技能说明
正文内容……

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

1.1 四端存放位置

端 全局根 项目级根
Claude Code ~/.claude/skills（可用 A4API_CLAUDE_SKILLS_PATH 覆盖） <项目根>/.claude/skills
Codex ~/.codex/skills（可用 A4API_CODEX_SKILLS_PATH 覆盖） <项目根>/.codex/skills
dsh ~/.dsh/skills（可用 A4API_DSH_SKILLS_PATH 覆盖） <项目根>/.dsh/skills
ZCode ~/.zcode/skills（可用 A4API_ZCODE_SKILLS_PATH 覆盖） <项目根>/.zcode/skills

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

项目根列表持久化在数据目录的 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 端存在」徽章。

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 时，旧版先移入回收站再写入新内容，不静默覆盖。
  • 每对迁移写日志：每一对「源 → 目标」迁移都会写入 SkillMigration 日志（新→旧排序），单对失败不影响其余对的执行。

3.1 一键适配四端

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

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，不会打开资源管理器。

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. 项目根目录配置

「技能管理」页签右侧的「项目根目录」可配置扫描哪些项目：文本框一行一个绝对路径，保存时校验必须是已存在的绝对路径（相对路径、不存在路径、全空都会报错）。配置持久化到数据目录的 projects.json，项目视图据此分组展示。

8. 常见问题

问：迁移会把源端的 skill 移走吗？

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

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

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

问：想撤销一次误删除怎么办？

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

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

答：Codex 全局根下的 .system/ 及一切以点开头的目录被视为系统保留目录，一律跳过，不视为用户 skill。

问：ZCode 的 skill 放在哪里会被 a4api 管理？

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