tsl-devkit/SKILLS.md

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 <deploy_root>/scripts/playbook.py -config playbook.toml

其中 <deploy_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 当作“可检索的工作流模块”，而不是长篇教程：

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

若你的项目把本 Playbook 部署到项目内，文档根路径为 <deploy_root>/docs/...；其中 <deploy_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）
• style-cleanup：整理代码风格（优先使用仓库既有 formatter/lint 工具链）
• bulk-refactor-workflow：批量重构（安全做法 + 验证契约）

---

9. Third-party Skills

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

• superpowers.list
• ui-ux-pro-max.list
• andrej-karpathy-skills.list

部署链路：

• thirdparty/skill 分支保存上游快照 andrej-karpathy-skills/
• 自动同步后，karpathy-guidelines/ 会落到仓库内 skills/thirdparty/karpathy-guidelines/
• 运行 [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