6.5 KiB

Raw Blame History

SKILLS

本文件定义：如何在仓库中落地与维护 AI agent skills，并给出与本 Playbook（docs/ + rulesets/）配套的技能编写建议与内置技能清单。

支持的平台：

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

提示：本仓库将 skills 以可分发的形式放在 skills/，并提供脚本一键安装到对应平台目录。

1. 启用 skills（必做）

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

[features]
skills = true

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

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

{
  "skills": true
}

2. 本仓库的 skills 目录结构

本 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`

3. 安装到本机（推荐）

使用统一入口 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。

4. `SKILL.md` 最小规范

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

5. 使用方式

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

6. 设计原则（写给维护者）

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

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

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

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

8. 本 Playbook 原生 skills

位于 skills/（Playbook 自维护部分），当前共 3 个。第三方 skills 来源见第 9 节。

语言特定 Skills

当前仓库不再内置语言特定 skill；TSL 相关问题请直接查阅 rulesets/tsl/index.md 与 docs/tsl/。

通用工作流 Skills

commit-message：基于 staged diff 自动建议提交信息（:emoji: type(scope): subject）
gitea-fix-ci：诊断 Gitea Actions / PR checks 失败，先提取日志证据并形成修复计划，再按批准范围改代码
style-cleanup：整理代码风格（优先使用仓库既有 formatter/lint 工具链）

9. Third-party Skills

来源：skills/thirdparty/.sources/（第三方来源清单目录）。

superpowers.list
ui-ux-pro-max.list
andrej-karpathy-skills.list
brooks-lint.list
codebase-recon.list
codebase-migrate.list
uncle-bob-craft.list

部署链路：

thirdparty/skill 分支保存各上游快照，例如 andrej-karpathy-skills/、awesome-codex-skills/、antigravity-awesome-skills/
自动同步后，选中的下游 skill 会落到仓库内 skills/thirdparty/<skill-name>/
运行 [install_skills] 时，再复制到目标平台 skills 目录（~/.agents/skills/ 或 ~/.claude/skills/）
该 skill 本身不依赖 Playbook 文档路径重写，也不需要像 ui-ux-pro-max 那样额外渲染

10. 运行时排障

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

最后更新：2026-01-26

6.5 KiB Raw Blame History Unescape Escape