# 多工具 Skill 适配

只维护一份 Skill 正文。优先采用开放 Agent Skills 格式：一个目录包含 `SKILL.md`，并按需包含 `scripts/`、`references/`、`assets/` 和产品元数据。

## 推荐仓库结构

```text
repo/
├── AGENTS.md
├── agent-rules/
├── .agents/
│   └── skills/
│       └── deliver-frontend-requirement/
└── .claude/
    └── skills/
        └── deliver-frontend-requirement -> ../../.agents/skills/deliver-frontend-requirement
```

使用 `.agents/skills` 作为唯一正文源，因为 Codex 和多个客户端支持这个跨 Agent 目录。Claude Code 的官方项目目录是 `.claude/skills`，因此为它提供薄适配。

## 适配方案

### 相对符号链接

适合开发者和 CI 使用能够保留符号链接的文件系统及 Git 客户端的团队。

```bash
mkdir -p .claude/skills
ln -s ../../.agents/skills/deliver-frontend-requirement \
  .claude/skills/deliver-frontend-requirement
```

规则：

- 链接目标必须留在仓库内；
- 使用相对路径；
- 提交符号链接本身；
- 在 CI 的干净 Clone 中验证；
- 说明 Windows `core.symlinks` 或文件系统要求。

### 生成镜像

适合 Windows 用户较多，或目标客户端不能稳定跟随符号链接的团队。

1. 让 `.agents/skills` 始终保持权威。
2. 用确定性脚本生成厂商目录。
3. 永远不要手动编辑生成副本。
4. 在 CI 中重新生成，并在存在非空 Diff 时失败。
5. 客户端允许时，在 `SKILL.md` Frontmatter 之外标记生成文件。

### Installer / Plugin

适合跨很多仓库分发或需要同时打包连接器的团队。Skill 保持工作流正文，由 Installer 把适配副本安装到不同客户端目录。安装前审查脚本和工具权限，发布时使用明确版本。

## 项目规则

使用 `AGENTS.md` 承载简短、长期有效的项目事实和验证命令。长任务流程放进 Skill，或放进 `agent-rules/` 这类路由目录。Claude Code 需要相同长期规则时，先验证客户端支持，再使用薄 `CLAUDE.md` 导入或仓库内符号链接。不要长期维护两份完整指令正文。

## 可移植性边界

除非所有目标客户端都接受扩展字段，否则通用 `SKILL.md` Frontmatter 只写标准 `name` 和 `description`。产品专属元数据放入 `agents/` 或厂商适配层。工具名称应抽象成能力：核心流程写“使用已授权 Figma 连接器”，具体产品路由另行配置，不要把单个 MCP 函数名硬编码进通用工作流。