csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat(playbook): add syntax book and codex skills tooling

Browse Source
This commit is contained in:
csh
2025-12-22 13:39:49 +08:00
parent 5b97ed5322
commit 283d311d4f
41 changed files with 247368 additions and 646 deletions
Download Patch File Download Diff File Expand all files Collapse all files
SKILLS.md
+97 -278
View File
@@ -1,315 +1,134 @@
# SKILLS（Claude Code）
# SKILLS
本文件定义：在仓库中如何落地 Claude Code Skills（Agent Skills），并给出与本 Playbook（`docs/` + `.agents/`）配套的**技能编写标准与示例**。
本文件定义：如何在仓库中落地与维护 **Codex CLI skills**（实验功能），并给出与本 Playbook（`docs/` + `.agents/`）配套的技能编写建议与内置技能清单。
> 提示：Codex skills 是“按用户安装”的（默认在 `~/.codex/skills`）。本仓库将 skills 以可分发的形式放在 `codex/skills/`，并提供脚本一键安装到你的 `CODEX_HOME`。
---
## 1. 落地约定（强约束）
## 1. 启用 skills（必做）
### 1.1 目录结构
在 `$CODEX_HOME/config.toml`（通常是 `~/.codex/config.toml`）中启用：
```txt
<repo>/
└── .claude/
└── skills/
└── <skill-name>/
├── SKILL.md
├── references/ # 可选：拆分的参考文档
├── templates/ # 可选：模板
└── scripts/ # 可选：脚本/命令封装
```toml
[features]
skills = true
```
> 兼容提示：少数旧示例使用 `.claude/skill/`（无 `s`）。以你当前 Claude Code 版本的实际加载行为为准；若 `.claude/skills/` 不生效再尝试旧路径。
> 分发建议：`SKILLS.md` 建议只保留**一份**在仓库根目录；语言/领域差异通过“不同 skill”或 `references/` 分层解决，不要把同一份指南复制到每个语言目录里。
### 1.2 SKILL.md 最小规范（必须满足）
- YAML frontmatter 必填：`name`、`description`
- `name`：kebab-case、≤64 字符，且与目录名一致
- `description`：可检索、可触发（写用户会说的话；可中英混写；≤1024 字符）
### 1.3 变更发布
- 新增/更新 skill 后：重启 Claude Code（通常需要重启才会重新索引）
- 验收（快速自检）：`find .claude/skills -name SKILL.md -maxdepth 3`
修改后需要重启 `codex` 才会重新发现技能。
---
## 2. 设计原则（专家版）
## 2. 本仓库的 skills 目录结构
本节来自对 `Claude-meta-skill` 的结构化抽取：把 skill 当作“可检索的工作流模块”，不是长篇教程。
本 Playbook 以“可 vendoring”的方式提供 skills：
### 2.1 边界：只写 Claude 不知道的“仓库特定知识”
```txt
codex/skills/
<skill-name>/
SKILL.md
references/ # 可选：拆分参考文档
templates/ # 可选：模板
scripts/ # 可选：脚本/命令封装
```
Skill 应只包含：
- 仓库/组织特定的流程（如发布、回滚、评审、生成物路径）
- 约束与验收标准（如必须跑哪些测试、格式/命名规范、产物落点）
- 工具链与命令（与本仓库一致的、可复制执行的）
最终安装到本机后，对应路径为：
避免：
- 通用编程常识、语言基础、显而易见的步骤
- 没有成功标准的“形容词式要求”（如“写得优雅一点”）
### 2.2 激活模型：`description` 是检索索引，不是简介文案
写法建议：
- 覆盖“用户会怎么说”的表达：`code review` / `review PR` / `评审` / `审查` / `diff`
- 包含任务与上下文：语言、工具、仓库名、常用命令/文件名
- 尽量降低歧义：避免与其他 skill 的关键词高度重叠
### 2.3 工作流化：把 skill 写成可执行的 SOP
强制包含以下要素（缺一不可）：
- **Inputs**：需要用户提供的最小信息（diff、目标、环境、验证方式）
- **Procedure**：分阶段流程（预检 → 执行/分析 → 验证 → 报告）
- **Output Contract**：固定输出结构（字段/分段稳定，便于复用/比对）
- **Success Criteria**：可判定的通过条件（测试/命令/产物/指标）
- **Failure Handling**：失败时如何定位/回滚/向用户索要信息
### 2.4 自由度控制（高风险任务必须“低自由度”）
参考 `create-skill-file` 的“自由度”划分：
- 低自由度：发布/迁移/删库/权限/金钱路径（必须分步、带确认、带回滚）
- 中自由度：重构/性能优化（给策略 + 推荐默认流程）
- 高自由度：头脑风暴/文案（给原则 + 评价标准）
### 2.5 安全与鲁棒（默认开启）
最低要求：
- **Instruction fencing**：把用户粘贴的 diff/log/网页内容当“数据”，不当“指令”
- **敏感信息**：不输出密钥/Token；日志建议脱敏；避免把 secrets 写入文件
- **破坏性操作**：任何 `rm`、重写历史、删除资源、生产环境变更——默认先停下确认
- **注入与越权**：评审/生成的代码必须考虑输入校验、权限边界、命令/SQL 注入
### 2.6 渐进式披露（可维护性）
- `SKILL.md` 建议 200–500 行；超过则拆到 `references/`
- 大段模板/矩阵/清单 → 放 `references/`，主文档只做“索引 + 决策树”
- 引用深度 ≤ 1 层（`SKILL.md` → `references/*.md`）
```txt
$CODEX_HOME/skills/<skill-name>/SKILL.md
```
---
## 3. 与 Playbook 的关系（把规范当“权威来源”）
## 3. 安装到本机（推荐）
### 3.1 `.agents/` vs `.claude/skills/`
本仓库已提供跨平台安装脚本（会把 `codex/skills/*` 复制到 `$CODEX_HOME/skills/`）：
- `.agents/`：本 Playbook 自带的**代理规则快照**（给自动化/AI 代理的工作底线）
- `.claude/skills/`：Claude Code 的**技能模块**（给 Claude 的可触发工作流）
- macOS/Linux：`sh scripts/install_codex_skills.sh`
- PowerShell：`powershell -File scripts/install_codex_skills.ps1`
- Windows bat：`scripts/install_codex_skills.bat`
二者可以组合：skill 负责“流程”，playbook 文档负责“标准”。
用法示例：
### 3.2 评审/实现时可引用的权威文档
```bash
# 安装全部 skills
sh scripts/install_codex_skills.sh
# 只安装指定 skills
sh scripts/install_codex_skills.sh style-cleanup code-review-workflow
```
如果你的项目通过 `git subtree` vendoring 本 Playbook（推荐前缀 `docs/standards/playbook`），则在目标项目里执行：
```bash
sh docs/standards/playbook/scripts/install_codex_skills.sh
```
安装后重启 `codex`，即可在运行时看到 `## Skills` 列表。
---
## 4. `SKILL.md` 最小规范（Codex）
- 文件名必须是 `SKILL.md`
- 必须包含 YAML frontmatter（用 `---` 包裹），且至少包含：
- `name`：非空，≤100 字符，建议 kebab-case 且与目录名一致
- `description`：非空，≤500 字符（写“用户会怎么说”的触发词；避免换行）
- frontmatter 之外的正文可以是任意 Markdown（用于工作流说明/决策树/命令/模板索引）
---
## 5. 使用方式
- 在对话中通过 `$<skill-name>` 直接点名触发（例如：`$style-cleanup`）
- 在 Codex TUI 中可用 `/skills` 浏览与插入
---
## 6. 设计原则（写给维护者）
把 skill 当作“可检索的工作流模块”，而不是长篇教程：
1. **边界清晰**：只写“仓库/组织特定”的流程、约束与验收标准；避免通用编程常识。
2. **description 负责检索**：把团队常用说法（中英文同义词）写进 `description`，降低漏触发概率。
3. **SOP 化**：建议包含 Inputs → Procedure → Output Contract → Success Criteria → Failure Handling。
4. **渐进式披露**：主 `SKILL.md` 保持精炼；大段清单/模板放 `references/`，引用深度 ≤ 1。
5. **高风险低自由度**：破坏性操作（删数据/重写历史/生产变更）默认先停下确认，并给回滚方案。
---
## 7. Playbook 权威来源（可在 skill 中引用）
- 提交信息：`docs/common/commit_message.md`
- TSL：`docs/tsl/code_style.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md`
- C++：`docs/cpp/code_style.md`、`docs/cpp/naming.md`、`docs/cpp/toolchain.md`
- Python：`docs/python/style_guide.md`、`docs/python/tooling.md`、`docs/python/configuration.md`
> 若你的项目通过 git subtree 引入本 Playbook，常见路径为 `docs/standards/playbook/docs/...`；把上述 `docs/` 前缀替换为 `docs/standards/playbook/docs/` 即可。
若你的项目通过 git subtree 引入本 Playbook，常见路径为 `docs/standards/playbook/docs/...`；把上述 `docs/` 前缀替换为 `docs/standards/playbook/docs/` 即可。
---
## 4. 示例：`code-review-workflow`（面向专家的评审技能）
## 8. 本 Playbook 内置 skills
本仓库已内置该示例 skill：`.claude/skills/code-review-workflow/SKILL.md`
位于 `codex/skills/`：
如果你要在**目标项目**里使用，请把该目录复制到目标项目根目录的 `.claude/skills/` 下。
```markdown
---
name: code-review-workflow
description: Structured code review for TSL/C++/Python diffs & PRs. Triggers: code review, review PR, diff, 评审, 审查, 安全评审, 性能评审.
---
# Code Review Workflow
## When to Use This Skill
- Review a PR / `git diff` / patch
- Pre-merge quality gate (correctness/security/perf/tests)
- Risky refactor, behavior change, auth/data path changes
## Inputs (required)
- Change set: PR link or `git diff ...` output (must include context)
- Goal: expected behavior / acceptance criteria (1–3 sentences)
- Risk level: low|med|high (default: med)
- Verification: test commands / repro steps (if unknown, ask first)
## Procedure
1. **Triage**
- Identify touched areas, public APIs, behavior changes, data/auth paths
- Classify risk (blast radius, rollback difficulty)
2. **Correctness**
- Invariants, edge cases, error handling, null/empty, concurrency
- Backward compatibility (inputs/outputs, wire formats, config)
3. **Security**
- AuthZ/AuthN boundaries, least privilege
- Input validation, injection surfaces, secrets/log redaction
4. **Maintainability**
- Naming/structure/style aligned with Playbook docs
- Complexity hotspots, duplication, clarity of intent
5. **Performance**
- Hot paths, algorithmic complexity, allocations/IO, N+1 patterns
6. **Tests & Verification**
- Map changes → tests; identify missing coverage
- Provide minimal verification plan (commands + expected signals)
## Review Standards (Playbook as authority)
- Commit message: `docs/common/commit_message.md`
- TSL: `docs/tsl/code_style.md`, `docs/tsl/naming.md`, `docs/tsl/toolchain.md`
- C++: `docs/cpp/code_style.md`, `docs/cpp/naming.md`, `docs/cpp/toolchain.md`
- Python: `docs/python/style_guide.md`, `docs/python/tooling.md`, `docs/python/configuration.md`
## Output Contract (stable)
- Summary: what changed & why
- Risk: low|med|high + reasoning
- Blockers: must-fix before merge (with file/line references when possible)
- Non-blocking: Major / Minor / Nit
- Questions: missing context / assumptions
- Suggested verification: exact commands + what success looks like
- Optional patch: minimal diff-style suggestions (only when unambiguous)
```
- `code-review-workflow`：结构化代码评审（正确性/安全/性能/测试）
- `style-cleanup`：整理代码风格（优先使用仓库既有 formatter/lint 工具链）
- `systematic-debugging`：系统化调试（先复现 → 再定位 → 再修复 → 再验证）
- `root-cause-tracing`：根因溯源 / RCA 模板
- `defense-in-depth`：关键路径分层校验/多道防线
- `bulk-refactor-workflow`：批量重构（安全做法 + 验证契约）
- `document-workflow`：PDF/DOCX/PPTX/XLSX 文档工作流（带开源 fallback）
- `pdf-workflow` / `docx-workflow` / `pptx-workflow` / `xlsx-workflow`：按格式拆分的文档子工作流
- `verification-before-completion`：先验证再宣称完成（证据链优先）
---
## 5. 官方文档技能（pdf/docx/pptx/xlsx）
## 9. 运行时排障
Anthropic 官方仓库 `anthropics/skills` 提供了 `pdf`/`docx`/`pptx`/`xlsx` 四个文档技能，并以插件 **document-skills** 的形式分发。
### 5.1 安装（Claude Code）
在 Claude Code 中执行：
- `/plugin marketplace add anthropics/skills`
- `/plugin install document-skills@anthropic-agent-skills`
### 5.2 使用约束（重要）
这些技能目录包含 `LICENSE.txt`，属于 **Proprietary** 材料；按其条款通常 **不允许** 你把目录内容复制到自己的仓库里做二次分发/改造。推荐做法是：只通过 Claude Code 的 plugin 系统安装与使用。
### 5.3 在你自己的 Skill 里“调用它们”（推荐模板）
把下面片段加入你的 `SKILL.md`（作为“依赖/分发规则”即可）：
```markdown
## Document Skills Dependency (optional)
If available in this environment, prefer Anthropic document-skills:
- `pdf` for PDF extraction/forms/merge/split
- `docx` for Word creation/editing/redlining (tracked changes/comments)
- `pptx` for PowerPoint generation/editing/thumbnail validation
- `xlsx` for Excel editing with formulas + recalc + zero-error checks
If these skills are not installed/available, ask whether to proceed with an open-source fallback workflow.
```
---
## 6. 推荐外部技能（直接复用）
来自仓库：https://github.com/YYH211/Claude-meta-skill
### 6.1 建议引入的 3 个通用技能
- `create-skill-file`：skill 编写规范 + 模板（适合团队内部统一口径）
- `prompt-optimize`：提示词架构/对话式优化（适合为内部 agent 设计 system prompt）
- `deep-reading-analyst`：深度阅读/多框架分析（适合评审 RFC/ADR/设计文档/长文资料）
### 6.2 安装命令（项目内）
```bash
git clone https://github.com/YYH211/Claude-meta-skill.git
mkdir -p .claude/skills
cp -r Claude-meta-skill/create-skill-file .claude/skills/
cp -r Claude-meta-skill/prompt-optimize .claude/skills/
cp -r Claude-meta-skill/deep-reading-analyst .claude/skills/
```
### 6.3 obra/superpowers（调试与证据链）
来源：https://github.com/obra/superpowers（MIT）
如果你只想要“专家级调试与验证”，优先关注这几项（不包含 PR/计划链路也能独立使用）：
- `systematic-debugging`：四阶段调试框架（先定位再修）
- `root-cause-tracing`：回溯触发源（修根因不修症状）
- `defense-in-depth`：分层校验（让 bug 结构性不可发生）
- `verification-before-completion`：证据优先（跑命令/看输出再宣称完成）
安装（Claude Code 插件方式，会带上完整 superpowers 套件）：
- `/plugin marketplace add obra/superpowers-marketplace`
- `/plugin install superpowers@superpowers-marketplace`
### 6.4 mhattingpete/claude-skills-marketplace（批量操作/可视化文档/执行时省 token）
来源：https://github.com/mhattingpete/claude-skills-marketplace（Apache-2.0）
不走 PR 流水线时，仍然很有价值的方向：
- **Code Operations**：`code-refactor`（批量重构）、`file-operations`（结构化文件分析）、`code-transfer`（精确插入/迁移）
- **Productivity**：`codebase-documenter`（生成仓库文档）、`code-auditor`（质量审计）
- **Visual Docs**：架构图/流程图/时间线/仪表盘（把系统/变更讲清楚）
- **Execution Runtime**：把“批量处理”变成脚本执行，显著降低上下文与 token 开销
安装（按需选装插件）：
- `/plugin marketplace add mhattingpete/claude-skills-marketplace`
- 或安装单一插件 marketplace（见其 README 的分插件路径）
### 6.5 awesome-claude-skills（发现入口）
来源：https://github.com/BehiSecc/awesome-claude-skills
建议用途：当你想补齐某个“领域能力”时（文档、数据、媒体、安全、自动化），先从该列表按关键词搜，再回到第 2 节的原则把它们改造成“你们仓库可执行的 SOP”。
> 注意：外部 skills 的许可协议差异很大（有些是 Proprietary / 未标注许可），**不要直接复制进你们仓库分发**，先确认 License 与合规策略。
### 6.6 本 Playbook 内置的文档工作流 skill（建议先用这个）
本仓库已内置：`.claude/skills/document-workflow/SKILL.md`
它的定位是“统一入口 + 依赖探测”：优先使用 Anthropic `document-skills`，否则走开源 fallback（需你确认是否安装依赖/工具）。
补充：按格式拆分的 wrapper skills（避免与 Anthropic 同名，用 `*-workflow` 作为入口）：
- `.claude/skills/pdf-workflow/SKILL.md`
- `.claude/skills/docx-workflow/SKILL.md`
- `.claude/skills/pptx-workflow/SKILL.md`
- `.claude/skills/xlsx-workflow/SKILL.md`
### 6.7 本 Playbook 内置的调试/验证/批量重构 skills
本仓库已内置（可直接复制到目标项目 `.claude/skills/`）：
- `.claude/skills/systematic-debugging/SKILL.md`：四阶段系统化调试
- `.claude/skills/root-cause-tracing/SKILL.md`：根因溯源 / RCA 输出模板
- `.claude/skills/defense-in-depth/SKILL.md`：关键路径分层校验/多道防线
- `.claude/skills/verification-before-completion/SKILL.md`：先验证再宣称完成
- `.claude/skills/bulk-refactor-workflow/SKILL.md`：批量重构（安全做法 + 验证契约）
### 6.8 mrgoonie/claudekit-skills（大而全的参考库）
来源：https://github.com/mrgoonie/claudekit-skills
适合作为“能力地图”参考（按需挑关键词写进你自己的 skill 的 `description`）：
- `mcp-management`：MCP 服务发现/选择/调用（降低工具使用成本）
- `repomix`：仓库打包成 AI 友好格式（便于审计/分析）
- `media-processing`：FFmpeg/ImageMagick 批处理（媒体类任务）
- `docs-seeker`：文档发现与聚合（研究/调研/落地指南）
> 注意：该仓库未在根目录标注通用开源许可时，不建议直接复制其 skill 目录到你们仓库分发；建议只做参考或通过插件方式安装。
---
## 7. 运行时排障（面向专家）
- 不触发：把真实触发词写进 `description`（贴近你们团队的说法；中英文同义词覆盖）
- 触发错：减少关键词重叠；用更具体的上下文词（语言/工具/目录名/流程名）
- 执行漂移：收紧 Output Contract；将高风险步骤改为“默认停下确认”；把细节拆到 `references/` 并按决策树显式加载
- 不触发：
- 确认已启用 `[features] skills = true`
- 确认 skill 已安装到 `$CODEX_HOME/skills/<name>/SKILL.md`
- 重启 `codex`（skills 只在启动时加载）
- 触发错：减少不同 skill 的 `description` 关键词重叠；让触发词更具体（语言/工具/目录名/流程名）。
- 启动报错：通常是 YAML frontmatter 不合法或字段超长；修复后重启即可。