如何编写真正有效的 AI Agent Skill：SKILL.md 模式详解

your-skill-name/
├── SKILL.md          # 必需：指令 + 元数据
├── scripts/          # 可选：agent 运行的可执行代码
├── references/       # 可选：仅在需要时加载的文档
└── assets/           # 可选：模板、图片、字体

1. 会话开始
   --> agent 加载：每个 skill 的 name + description（每个约 100 个 token）
2. 用户询问：“你能为这个项目写一个 README 吗？”
   --> agent 读取：readme-writer/SKILL.md 完整主体（Level 2）
3. SKILL.md 引用了一个风格指南文件
   --> agent 读取：readme-writer/references/style.md（Level 3）
4. SKILL.md 包含一个验证脚本
   --> agent 执行：scripts/validate.sh 
   （运行而不被读入上下文）

# Claude Code 中的直接调用
/readme-writer
# 或者只需描述任务，Claude 会自动激活它
你能为这个项目写一个 README 吗？

# Codex CLI 中的显式调用
$readme-writer document this project
# 或者使用 skill 选择器
/skills

[skill 做什么] + [何时使用它，带有特定的触发短语]

description: 帮助处理文档。

description: 使用高级格式创建复杂的多页文档。

description: 为软件项目创建和编写专业的 README.md 文件。当用户要求"写一个 README"、"创建一个 readme"、"记录这个项目"、"生成项目文档"或"帮我写一个 README.md"时使用。

## 创建 skill 目录
mkdir -p ~/.claude/skills/readme-writer

---
name: readme-writer
description: 为软件项目创建和编写专业的 README.md 文件。当用户要求"写一个 README"、"创建一个 readme"、"记录这个项目"、"生成项目文档"或"帮我写一个 README.md"时使用。适用于项目描述、现有代码或两者。
---

# README 编写器

## 概述

生成一个完整、专业的 README.md 文件并将其写入磁盘。输出应该足够清晰，让第一次贡献者能够理解项目、在本地设置并开始贡献。

## 步骤 1：收集项目上下文

在询问用户之前，先在代码库中寻找上下文：

\```bash
ls -la
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
  cat go.mod 2>/dev/null || echo "未找到清单文件"
ls .env.example .env.sample 2>/dev/null || echo "未找到环境变量示例"
\```

收集：
- 这个项目做什么？（1-2 句话总结）
- 它使用什么语言和主要框架？
- 如何安装和运行它？
- 需要环境变量吗？
- 有 LICENSE 文件吗？

## 步骤 2：编写 README

使用此结构。仅包含相关的部分。不要添加空的部分。

\```
# 项目名称

一句话清晰描述这个项目做什么以及为谁服务。

## 功能
- 功能一（具体说明）
- 功能二

## 先决条件
列出需要安装的内容。如果重要，包括版本要求。

## 安装
逐步设置。每个命令必须可复制粘贴。

\```bash
git clone https://github.com/username/project
cd project
npm install
\```

## 配置
如果项目需要环境变量，显示一个示例：

\```bash
cp .env.example .env
\```

然后解释用户需要手动设置的每个变量。

## 使用
首先显示最常见的用例。

\```bash
npm run dev
\```

## 许可证
[MIT](LICENSE)
\```

## 步骤 3：将文件写入磁盘

内容准备好后，写入：

\```bash
cat > README.md << 'EOF'
[完整的 readme 内容]
EOF
\```

确认已写入：

\```bash
echo "README.md 已写入：$(wc -l < README.md) 行"
\```

## 步骤 4：质量检查

完成前，验证：
- [ ] 没有像"[你的描述在这里]"这样的占位符文本
- [ ] 安装部分中的每个命令都适用于这个项目
- [ ] 先决条件匹配项目实际需要的内容
- [ ] 许可证部分匹配 LICENSE 文件（如果存在）

你能为这个项目写一个 README 吗？

mkdir -p ~/.claude/skills/git-commit-writer

---
name: git-commit-writer
description: 遵循 conventional commits 规范生成标准化的 git 提交消息。当用户要求"写一个提交消息"、"帮我提交"、"总结我的更改"、"我的提交应该说什么"或"起草一个提交"时使用。分析暂存的差异和更改描述，以生成 type(scope): description 格式的消息。
---

# Git 提交消息编写器

## 格式

\```
type(scope): 简短描述

[可选正文]

[可选页脚]
\```

允许的类型：feat、fix、docs、style、refactor、test、chore、perf、ci、build

## 指令

### 步骤 1：获取差异

\```bash
git diff --staged
\```

如果没有暂存任何内容：

\```bash
git diff HEAD
\```

### 步骤 2：分析更改

查找：
- 哪些文件更改了，它们属于什么类别
- 这是否添加了新功能（feat）、修复了错误（fix）还是更新了文档/配置/测试
- 作用域：哪个模块、组件或区域受到影响

### 步骤 3：编写消息

- 保持主题行在 72 个字符以下
- 使用祈使语气："添加功能"而不是"添加了功能"
- 不要以句号结束主题行
- 如果更改需要比主题行允许的更多上下文，则添加正文

### 质量检查

- [ ] 类型是允许的类型之一
- [ ] 主题行在 72 个字符以下
- [ ] 使用了祈使语气
- [ ] 作用域足够具体，有用

## 示例

\```
feat(auth): 添加 Google OAuth2 登录

使用现有的会话管理系统实现 Google OAuth2 流程。用户现在可以使用他们的 Google 账户登录。

关闭 #142
\```

\```
fix(api): 处理支付提供商的空响应
\```

\```
docs(readme): 为 Node 22 更新本地设置说明
\```

mkdir -p ~/.claude/skills/code-reviewer/references

---
name: code-reviewer
description: 进行结构化的代码审查，提供分类反馈。当用户要求"审查这段代码"、"检查我的 PR"、"查看这个函数"或"给我这个实现的反馈"时使用。产生结构化输出，将阻塞性问题与建议分开。
---

# 代码审查器

## 审查流程

### 步骤 1：理解上下文

审查前，确定：
- 这段代码应该做什么？
- 它使用什么语言和框架？
- 这是一个新功能、错误修复还是重构？

### 步骤 2：运行审查

有关按类别的详细审查标准，请参见 [references/criteria.md](references/criteria.md)。

按顺序处理每个类别。即使某些类别似乎不太可能有问题，也不要跳过。

### 步骤 3：结构化输出

\```
## 总结
[2-3 句话概述和整体评估]

## 阻塞性问题
[必须修复的问题：安全漏洞、逻辑错误、数据丢失风险。
如果没有，写"未找到。"]

## 建议
[非阻塞性改进，编号。包括位置、原因以及如何修复每个问题。]

## 积极方面
[代码做得好的地方。始终至少包含一个。]
\```

# 审查标准

## 安全（首先检查）
- SQL 注入：用户输入是否参数化？
- XSS：输出在渲染前是否被正确转义？
- 身份验证检查：受保护的路由是否真正受到保护？
- 密钥：API 密钥或凭据是否硬编码在任何地方？
- 输入验证：是否在服务器端进行验证？

## 正确性
- 逻辑是否符合所述意图？
- 是否处理了边缘情况：空数组、空值、零、负数？
- 错误状态是否正确呈现？
- 异步操作是否正确等待？

## 可读性
- 新团队成员能在 5 分钟内理解吗？
- 变量和函数名是否具有描述性？
- 函数是做一件事还是多件事？

## 性能
- 是否有明显的 N+1 查询模式？
- 昂贵的操作是否在循环内部，而本可以在外部？

## 测试
- 是否有针对新行为的测试？
- 是否测试了边缘情况，而不仅仅是快乐路径？

mkdir -p ~/.claude/skills/linear-sprint-planner/references

---
name: linear-sprint-planner
description: 自动化 Linear 冲刺规划，包括周期创建、待办事项分类和任务分配。当用户说"规划冲刺"、"设置下一个周期"、"帮我优先处理待办事项"或"在 Linear 中创建冲刺任务"时使用。需要连接 Linear MCP 服务器。
metadata:
  mcp-server: linear
  version: 1.0.0
---
# Linear 冲刺规划器

## 先决条件

验证 Linear MCP 服务器是否已连接。如果不可用，告诉用户先在 MCP 设置中连接它。

## 流程

### 步骤 1：收集当前状态

按顺序从 Linear 获取：
1. 当前活动周期和完成百分比
2. 所有待办事项（状态：Backlog 或 Todo，未分配给任何周期）
3. 团队成员和当前工作量
4. 任何标记为高优先级的事项

有关分页和速率限制处理，请参见 [references/linear-api.md](references/linear-api.md)。

### 步骤 2：分析容量

- 计算参与冲刺的团队成员数量
- 估算点数（默认：除非有历史速度，否则每人每周 10 点）
- 减去计划的休假时间

继续前呈现摘要：
团队容量：- [N] 名工程师 × [X] 点 = [总计] 可用 - 结转：[X] 点 - 新增容量：[X] 点
### 步骤 3：优先处理待办事项

按此顺序排序：
1. P0/P1 错误和阻塞项（始终包含）
2. 用户明确标记的事项
3. 解除其他团队阻塞的事项
4. 按产品优先级排序的功能
5. 技术债务

除非用户要求，否则不要超过容量的 10%。

### 步骤 4：呈现以供批准

在 Linear 中创建任何内容之前，显示建议的计划：
建议的冲刺 [N]：[日期范围] 容量：[X] 点 事项：- [ISSUE-123] 修复支付超时（P0）- 3 点 - [ISSUE-456] 添加 CSV 导出（P2）- 5 点 - [ISSUE-789] 重构身份验证中间件 - 2 点 总计：[X] / [X] 点 我应该创建这个周期并分配这些事项吗？
在进行更改之前，始终等待确认。

### 步骤 5：创建并确认

一旦批准：
1. 使用商定的日期范围创建周期
2. 将每个事项添加到周期中
3. 如果用户指定了所有者，则更新分配
4. 返回带有 Linear 周期链接的摘要

如果任何 API 调用失败，请参见 [references/error-handling.md](references/error-handling.md)。

# Linear API 模式
## 获取待办事项
以 50 个为一批进行分页。检查 pageInfo.hasNextPage 并使用 after 游标。
过滤：status [Backlog, Todo], cycle: null。
## 创建周期
必需：name、startsAt、endsAt、teamId
## 添加事项
使用 issueUpdate mutation 设置 cycleId。尽可能批量处理。
## 速率限制
遇到 429 时：等待 1 秒，重试一次。如果再次失败，向用户报告并继续。

# 错误处理
## MCP 连接错误
告诉用户："Linear MCP 似乎已断开连接。请在运行冲刺规划之前重新连接。"不要继续。
## 缺少数据
使用可用数据继续。在最终摘要中注明缺少的内容。
## 周期创建失败
不要尝试添加事项。报告错误并建议检查权限。

帮我在 Linear 中规划下一个冲刺

---
name: log-analyzer
description: 分析应用程序日志文件以识别错误和模式。当用户说"检查日志"、"我的日志中有什么错误"或"分析这个日志文件"时使用。
allowed-tools: Read, Grep, Glob
---
# 日志分析器
1. 使用 Glob 查找日志文件：*.log、logs/*.log、/var/log/*.log
2. 使用 Grep 搜索错误模式：ERROR、FATAL、Exception、Traceback
3. 按类型和频率分组错误
4. 首先总结最常见的错误

mkdir -p .claude/skills/readme-writer
# 添加 SKILL.md，然后：
git add .claude/skills/
git commit -m "为团队添加 readme-writer skill"
git push

# Claude Code 个人 skill 
ls ~/.claude/skills/your-skill/SKILL.md
# Claude Code 项目 skill 
ls .claude/skills/your-skill/SKILL.md
# Codex
ls ~/.codex/skills/your-skill/SKILL.md

claude --debug

使用 readme-writer skill 记录这个项目