5.4 KiB

Raw Blame History

SKILLS

本文档说明如何安装、启用和使用 AI agent skills。

支持的平台：

平台	skills 目录
Codex CLI	`~/.agents/skills/`
Claude Code	`~/.claude/skills/`

用户指南

1. 启用 skills（必做）

Codex CLI — 在 ~/.codex/config.toml 中启用：

[features]
skills = true

修改后需要重启 codex 才会重新发现技能。

Claude Code — 在 ~/.claude/settings.json 中启用（或通过 /config 命令）：

{
  “skills”: true
}

2. 安装到本机

使用统一入口 playbook.py 安装 skills，通过 agents_home 指定目标平台目录：

Codex CLI：

# playbook.toml
[playbook]
project_root = “.”

[install_skills]
mode = “all”
agents_home = “~/.agents”

Claude Code：

[install_skills]
mode = “all”
agents_home = “~/.claude”

python scripts/playbook.py -config playbook.toml

仅安装指定 skills：

[install_skills]
mode = “list”
skills = [“style-cleanup”, “commit-message”]
agents_home = “~/.claude”   # 或 ~/.agents

[install_skills] 默认会先把已存在的 skill 目录重命名为 *.bak.<timestamp>，再复制新版本，便于手动回退。若不需要备份：

[install_skills]
mode = “all”
agents_home = “~/.claude”
no_backup = true

如果你的项目已经把本 Playbook 部署到项目内，则在目标项目里执行：

python <playbook_root>/scripts/playbook.py -config playbook.toml

其中 <playbook_root> 默认为 docs/standards/playbook。

3. 使用方式

在对话中通过 $<skill-name> 直接点名触发（例如：$style-cleanup）
Codex TUI：可用 /skills 浏览与插入
Claude Code：通过 /skills 命令或直接在对话中触发

4. 可用 Skills 清单

完整清单（含作用说明、典型场景）见 skills/README.md。

5. 运行时排障

不触发：
- Codex：确认已启用 [features] skills = true，重启 codex
- Claude Code：确认 skills 已启用，重启 Claude Code
- 确认 skill 已安装到对应平台目录
触发错：减少不同 skill 的 description 关键词重叠；让触发词更具体（语言/工具/目录名/流程名）
启动报错：通常是 YAML frontmatter 不合法或字段超长；修复后重启即可

开发者指南

目录结构

本 Playbook 以"可分发、可安装"的方式提供 skills：

skills/
  <skill-name>/         # 本仓库自维护
    SKILL.md
    references/        # 可选：拆分参考文档
    templates/         # 可选：模板
    scripts/           # 可选：脚本/命令封装
  thirdparty/          # 第三方同步（不可手动修改）
    <skill-name>/
      SKILL.md
    .sources/          # 第三方来源清单

最终安装到本机后，对应路径为：

平台	路径
Codex CLI	`~/.agents/skills/<skill-name>/SKILL.md`
Claude Code	`~/.claude/skills/<skill-name>/SKILL.md`

`SKILL.md` 最小规范

文件名必须是 SKILL.md
必须包含 YAML frontmatter（用 --- 包裹），且至少包含：
- name：非空，≤100 字符，建议 kebab-case 且与目录名一致
- description：非空，≤500 字符（写”用户会怎么说”的触发词；避免换行）
frontmatter 之外的正文可以是任意 Markdown（用于工作流说明/决策树/命令/模板索引）

设计原则

把 skill 当作”可检索的工作流模块”，而不是长篇教程：

边界清晰：只写”仓库/组织特定”的流程、约束与验收标准；避免通用编程常识。
description 负责检索：把团队常用说法（中英文同义词）写进 description，降低漏触发概率。
SOP 化：建议包含 Inputs → Procedure → Output Contract → Success Criteria → Failure Handling。
渐进式披露：主 SKILL.md 保持精炼；大段清单/模板放 references/，引用深度 ≤ 1。
高风险低自由度：破坏性操作（删数据/重写历史/生产变更）默认先停下确认，并给回滚方案。

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

若你的项目把本 Playbook 部署到项目内，文档根路径为 <playbook_root>/docs/...；其中 <playbook_root> 默认为 docs/standards/playbook，也可以按项目配置改成 custom/playbook 等自定义目录。

第三方 Skills 同步机制

本仓库通过 thirdparty/skill 分支同步第三方 skills。

来源登记：

skills/thirdparty/.sources/：来源清单目录（*.list 文件）
skills/thirdparty/thirdparty-skills.yml：统一配置文件

同步流程：

上游快照保存在 thirdparty/skill 分支
自动同步后，落到仓库内 skills/thirdparty/<skill-name>/
运行 [install_skills] 时，复制到目标平台 skills 目录（~/.agents/skills/ 或 ~/.claude/skills/）

最后更新：2026-06-17

5.4 KiB Raw Blame History Unescape Escape