From 79cff6cc34254991ad020558856d6d571acb2fa9 Mon Sep 17 00:00:00 2001
From: csh <caoshenghui@tinysoft.com.cn>
Date: Fri, 15 May 2026 18:03:15 +0800
Subject: [PATCH] :memo: 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>
---
 SKILLS.md | 95 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 52 insertions(+), 43 deletions(-)

diff --git a/SKILLS.md b/SKILLS.md
index 2282a2a9..77c033c3 100644
--- a/SKILLS.md
+++ b/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 不合法或字段超长；修复后重启即可。
 
 ---