📝 docs(skills): add Claude Code platform support
- Rename "Codex CLI skills" to "AI agent skills" throughout - Add platform table: Codex CLI (~/.agents/skills/) vs Claude Code (~/.claude/skills/) - Document Claude Code enable steps (settings.json) alongside Codex config - Update install section with per-platform agents_home examples - Update troubleshooting section for both platforms - Update playbook.toml.example agents_home comment Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
452c6f58f9
commit
79cff6cc34
95
SKILLS.md
95
SKILLS.md
|
|
@ -1,17 +1,22 @@
|
|||
# SKILLS
|
||||
|
||||
本文件定义：如何在仓库中落地与维护 **Codex CLI skills**（实验功能），
|
||||
本文件定义：如何在仓库中落地与维护 **AI agent skills**，
|
||||
并给出与本 Playbook（`docs/` + `rulesets/`）配套的技能编写建议与内置技能清单。
|
||||
|
||||
> 提示：Codex skills 是“按用户安装”的（默认在
|
||||
> `~/.agents/skills`）。本仓库将 skills 以可分发的形式放在
|
||||
> `codex/skills/`，并提供脚本一键安装到你的 `~/.agents`。
|
||||
支持的平台：
|
||||
|
||||
| 平台 | skills 目录 |
|
||||
| --- | --- |
|
||||
| Codex CLI | `~/.agents/skills/` |
|
||||
| Claude Code | `~/.claude/skills/` |
|
||||
|
||||
> 提示：本仓库将 skills 以可分发的形式放在 `codex/skills/`，并提供脚本一键安装到对应平台目录。
|
||||
|
||||
---
|
||||
|
||||
## 1. 启用 skills（必做）
|
||||
|
||||
在 `$CODEX_HOME/config.toml`（通常是 `~/.codex/config.toml`）中启用：
|
||||
**Codex CLI** — 在 `~/.codex/config.toml` 中启用：
|
||||
|
||||
```toml
|
||||
[features]
|
||||
|
|
@ -20,6 +25,14 @@ skills = true
|
|||
|
||||
修改后需要重启 `codex` 才会重新发现技能。
|
||||
|
||||
**Claude Code** — 在 `~/.claude/settings.json` 中启用（或通过 `/config` 命令）：
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 本仓库的 skills 目录结构
|
||||
|
|
@ -41,24 +54,35 @@ codex/skills/
|
|||
|
||||
最终安装到本机后，对应路径为：
|
||||
|
||||
```txt
|
||||
~/.agents/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
| 平台 | 路径 |
|
||||
| --- | --- |
|
||||
| Codex CLI | `~/.agents/skills/<skill-name>/SKILL.md` |
|
||||
| Claude Code | `~/.claude/skills/<skill-name>/SKILL.md` |
|
||||
|
||||
---
|
||||
|
||||
## 3. 安装到本机（推荐）
|
||||
|
||||
使用统一入口 `playbook.py` 安装 skills（会把 `codex/skills/*` 复制到 `~/.agents/skills/`）：
|
||||
使用统一入口 `playbook.py` 安装 skills，通过 `agents_home` 指定目标平台目录：
|
||||
|
||||
**Codex CLI：**
|
||||
|
||||
```toml
|
||||
# playbook.toml
|
||||
[playbook]
|
||||
project_root = "."
|
||||
project_root = “.”
|
||||
|
||||
[install_skills]
|
||||
mode = "all" # list|all
|
||||
agents_home = "~/.agents"
|
||||
mode = “all”
|
||||
agents_home = “~/.agents”
|
||||
```
|
||||
|
||||
**Claude Code：**
|
||||
|
||||
```toml
|
||||
[install_skills]
|
||||
mode = “all”
|
||||
agents_home = “~/.claude”
|
||||
```
|
||||
|
||||
```bash
|
||||
|
|
@ -69,46 +93,31 @@ python scripts/playbook.py -config playbook.toml
|
|||
|
||||
```toml
|
||||
[install_skills]
|
||||
mode = "list"
|
||||
skills = ["style-cleanup", "commit-message"]
|
||||
mode = “list”
|
||||
skills = [“style-cleanup”, “commit-message”]
|
||||
agents_home = “~/.claude” # 或 ~/.agents
|
||||
```
|
||||
|
||||
如果希望“项目内本地安装”（不污染全局）：
|
||||
`[install_skills]` 默认会先把已存在的 skill 目录重命名为 `*.bak.<timestamp>`，再复制新版本，便于手动回退。若不需要备份：
|
||||
|
||||
```toml
|
||||
[install_skills]
|
||||
mode = "all"
|
||||
agents_home = "./.agents"
|
||||
# no_backup = true
|
||||
```
|
||||
|
||||
> 注意：Codex 默认从 `~/.agents/skills` 加载 skills；使用本地安装时，需要确保 Codex 能发现该路径。
|
||||
|
||||
`[install_skills]` 默认会先把已存在的 skill 目录重命名为 `*.bak.<timestamp>`，再复制新版本，便于手动回退。
|
||||
如果你希望安装过程不保留备份，而是“先删除旧目录，再复制新目录”，可显式设置：
|
||||
|
||||
```toml
|
||||
[install_skills]
|
||||
mode = "all"
|
||||
agents_home = "~/.agents"
|
||||
mode = “all”
|
||||
agents_home = “~/.claude”
|
||||
no_backup = true
|
||||
```
|
||||
|
||||
`no_backup = true` 适合 CI 或你已经用 Git 管理变更、只想要确定性覆盖安装的场景。
|
||||
|
||||
如果你的项目已经把本 Playbook 部署到项目内（无论来自 `git subtree`，还是外部 clone 后部署到自定义根目录），则在目标项目里执行：
|
||||
如果你的项目已经把本 Playbook 部署到项目内，则在目标项目里执行：
|
||||
|
||||
```bash
|
||||
python <deploy_root>/scripts/playbook.py -config playbook.toml
|
||||
```
|
||||
|
||||
其中 `<deploy_root>` 默认为 `docs/standards/playbook`，也可以是 `custom/playbook` 等自定义目录。
|
||||
|
||||
安装后重启 `codex`，即可在运行时看到 `## Skills` 列表。
|
||||
其中 `<deploy_root>` 默认为 `docs/standards/playbook`。
|
||||
|
||||
---
|
||||
|
||||
## 4. `SKILL.md` 最小规范（Codex）
|
||||
## 4. `SKILL.md` 最小规范
|
||||
|
||||
- 文件名必须是 `SKILL.md`
|
||||
- 必须包含 YAML frontmatter（用 `---` 包裹），且至少包含：
|
||||
|
|
@ -121,7 +130,8 @@ python <deploy_root>/scripts/playbook.py -config playbook.toml
|
|||
## 5. 使用方式
|
||||
|
||||
- 在对话中通过 `$<skill-name>` 直接点名触发（例如：`$style-cleanup`）
|
||||
- 在 Codex TUI 中可用 `/skills` 浏览与插入
|
||||
- Codex TUI：可用 `/skills` 浏览与插入
|
||||
- Claude Code：通过 `/skills` 命令或直接在对话中触发
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -181,7 +191,7 @@ python <deploy_root>/scripts/playbook.py -config playbook.toml
|
|||
|
||||
- `thirdparty/skill` 分支保存上游快照 `andrej-karpathy-skills/`
|
||||
- 自动同步后，`skills/karpathy-guidelines/` 会落到 `codex/skills/karpathy-guidelines/`
|
||||
- 运行 `[install_skills]` 时，再复制到 `~/.agents/skills/karpathy-guidelines/`
|
||||
- 运行 `[install_skills]` 时，再复制到目标平台 skills 目录（`~/.agents/skills/` 或 `~/.claude/skills/`）
|
||||
- 该 skill 本身不依赖 Playbook 文档路径重写，也不需要像 `ui-ux-pro-max` 那样额外渲染
|
||||
|
||||
---
|
||||
|
|
@ -189,11 +199,10 @@ python <deploy_root>/scripts/playbook.py -config playbook.toml
|
|||
## 10. 运行时排障
|
||||
|
||||
- 不触发：
|
||||
- 确认已启用 `[features] skills = true`
|
||||
- 确认 skill 已安装到 `$CODEX_HOME/skills/<name>/SKILL.md`
|
||||
- 重启 `codex`（skills 只在启动时加载）
|
||||
- 触发错：减少不同 skill 的 `description`
|
||||
关键词重叠；让触发词更具体（语言/工具/目录名/流程名）。
|
||||
- Codex：确认已启用 `[features] skills = true`，重启 `codex`
|
||||
- Claude Code：确认 skills 已启用，重启 Claude Code
|
||||
- 确认 skill 已安装到对应平台目录（`~/.agents/skills/` 或 `~/.claude/skills/`）
|
||||
- 触发错：减少不同 skill 的 `description` 关键词重叠；让触发词更具体（语言/工具/目录名/流程名）。
|
||||
- 启动报错：通常是 YAML frontmatter 不合法或字段超长；修复后重启即可。
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue