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

14 KiB
Raw Blame History

SKILLS（Claude Code）

本文件定义：在仓库中如何落地 Claude Code Skills（Agent Skills），并给出与本 Playbook（docs/ + .agents/）配套的技能编写标准与示例。

1. 落地约定（强约束）

1.1 目录结构

<repo>/
└── .claude/
    └── skills/
        └── <skill-name>/
            ├── SKILL.md
            ├── references/        # 可选：拆分的参考文档
            ├── templates/         # 可选：模板
            └── scripts/           # 可选：脚本/命令封装

兼容提示：少数旧示例使用 .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

2. 设计原则（专家版）

本节来自对 Claude-meta-skill 的结构化抽取：把 skill 当作“可检索的工作流模块”，不是长篇教程。

2.1 边界：只写 Claude 不知道的“仓库特定知识”

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）

3. 与 Playbook 的关系（把规范当“权威来源”）

3.1 .agents/ vs .claude/skills/

  • .agents/：本 Playbook 自带的代理规则快照（给自动化/AI 代理的工作底线）
  • .claude/skills/：Claude Code 的技能模块（给 Claude 的可触发工作流）

二者可以组合：skill 负责“流程”，playbook 文档负责“标准”。

3.2 评审/实现时可引用的权威文档

  • 提交信息：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/ 即可。

4. 示例：code-review-workflow（面向专家的评审技能）

本仓库已内置该示例 skill：.claude/skills/code-review-workflow/SKILL.md

如果你要在目标项目里使用，请把该目录复制到目标项目根目录的 .claude/skills/ 下。

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

5. 官方文档技能（pdf/docx/pptx/xlsx）

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（作为“依赖/分发规则”即可）：

## 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 安装命令（项目内）

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/ 并按决策树显式加载