[!info] related notes

• 所属 MOC: Coding Agent MOC
• 前置概念: Skills
• 并列概念: MCP 协议, Coding Agent Subagents
• 关系笔记: Autonomous Coding Agent, Agent 工程纪律

Coding Agent Skills

一句话定义

Coding Agent Skills 是把反复编写的长 prompt 沉淀为结构化、可复用的能力包，核心是 SKILL.md（指令）+ references/（知识）+ scripts/（确定性步骤）+ assets/（素材），按需渐进式加载而非全量塞入上下文。

为什么重要

在真实工程中，你经常重复同一类任务：修 bug 前先补测试、PR 前做 code review、架构分析要读特定目录。每次重新写 prompt 既不稳定又浪费时间。Skills 的价值在于：

• 输出一致性：同一类任务用同一套约束和流程
• 上下文效率：只在需要时加载，不占用主上下文
• 团队复用：提交到仓库后团队成员共享

核心结构

skill-name/
├── SKILL.md          # 核心入口：frontmatter (name/description) + 指令正文
├── references/       # 按需加载的知识：schema、API 说明、规则、示例
├── scripts/          # 确定性步骤：bash/python 脚本，防止 LLM 临场发挥不稳定
└── assets/           # 输出素材：模板、样式、logo

渐进式加载机制

1. 第一层 metadata：name + description 决定何时触发
2. 第二层 SKILL.md：选中后才读核心指令
3. 第三层支持资源：references/、scripts/、assets/ 按需读取

这是 Skills 省上下文的关键——大块知识放在 references/，脆弱步骤做成 scripts/，SKILL.md 保持精炼。

各产品的实现差异

维度	Codex	Claude Code
入口文件	SKILL.md（必须）	SKILL.md（必须）
存储位置	项目内 skills 目录	~/.claude/skills/ 或 .claude/skills/
触发方式	显式调用或 Codex 隐式选择	/skill-name 或 Claude 自动匹配
脚本执行	Codex 内置执行	Claude Code Bash 工具执行
录制能力	Record & Replay（macOS）	/run-skill-generator
插件打包	可随 Plugin 分发	可随 Plugin 分发

Codex 特有

• Record & Replay：在 macOS 上录制一次操作流程，Codex 自动整理成可复用 Skill
• Plugin 打包：Skills 可以和 MCP servers、App integrations 一起打包成 Plugin 分发
• 显式/隐式调用：可以通过 /skills 显式选择，也可以让 Codex 根据 description 自动匹配

Claude Code 特有

• Slash command 调用：/skill-name 直接触发
• /run-skill-generator：录制项目启动和验证流程，自动生成 Skill
• .claude/commands/：轻量级替代——纯 prompt 文件变成 /命令名，不需要完整 Skill 目录结构
• 与 Workflow 联动：Skill 的指令可以要求使用 Workflow 引擎做多 Agent 编排

最小例子

focused-repair/
├── SKILL.md
│   ---
│   description: Use when fixing one explicit blocker with tests first and minimal scope.
│   ---
│   # Focused Repair Pass
│   1. Identify the exact blocker.
│   2. Add or identify a failing test.
│   3. Make the smallest implementation change.
│   4. Run targeted verification.
│   5. Report root cause, files changed, and remaining risks.
├── references/
│   └── repair-checklist.md
└── scripts/
    └── run-targeted-tests.sh

最适合承载什么

类型	示例
固定流程	focused-repair、PR 前审查、changelog 生成
领域知识 + 输出规范	团队代码风格、架构文档模板
需要辅助脚本的任务	测试运行、格式化、数据转换

不适合承载什么

• 单个 API 调用 → 用 MCP tool
• 单个数据库查询 → 用 function calling
• 简单的一次性 prompt → 直接写在对话里

最短记忆方式

Skill = Prompt 入口 + Docs 参考 + Scripts 执行 + Assets 素材，按需渐进加载。

Related notes

• Skills
• Coding Agent MOC
• MCP 协议
• Agent 工程纪律