09. 自定义 Skill 开发

什么时候该自己写 Skill

  • 反复让 Claude 做同一件流程化的事 → 抽成 Skill
  • 你有一套个人/团队的工作流 → 写成 Skill 复用
  • 想强制 Claude 在某个场景下走标准流程 → 写 Skill

Skill 文件结构

~/.claude/skills/<skill-name>/
└── SKILL.md        ← 唯一必需的文件

SKILL.md 顶部必须有 YAML frontmatter:

---
name: <skill-name>
description: <触发条件,要写得清晰具体>
---

<指令正文,Markdown 格式>

写好 description 的 5 条原则

  1. 说明何时使用(Use when...)
  2. 说明适用领域(在什么类型的项目上)
  3. 说明触发关键词(用户说什么话时该用)
  4. 说明输出预期(大致产出什么)
  5. 避免模糊词("help with"、"useful for" 这种没用)

反例 vs 正例

❌ 反例:

description: Helps with Python code

✅ 正例:

description: Use when refactoring Python data processing code - enforces pandas over loops, requires vectorized operations, and adds benchmark comparisons before/after

Skill 正文的结构

推荐四段式:

## 适用场景
(详细说明什么时候用,补充 description 没覆盖的边界)

## 步骤
1. 第一步具体做什么
2. 第二步具体做什么
...

## 输出格式
(规定输出长什么样,模板、字段)

## 反例 / 不要做
(明确禁止的行为)

示例:课程作业初评 Skill

---
name: assignment-feedback
description: Use when reviewing or grading student programming assignments - provides structured, encouraging feedback focused on correctness, style, and learning opportunities without assigning scores
---

## 适用场景

学生提交编程作业后,需要给出书面反馈。
**不**给出具体分数(留给老师最终决定)。
**不**替学生改代码(只指出问题和方向)。

## 步骤

1. 先读取作业要求文档(ask user if path unclear)
2. 运行代码或测试,记录所有错误和警告
3. 阅读源代码,关注:
   - 正确性:核心逻辑是否解决题目
   - 风格:命名、缩进、注释
   - 边界:空输入、负数、超大输入
   - 复杂度:是否有明显可优化的地方
4. 输出三段式反馈:
   - ✅ 做得好的(具体指出 2-3 点)
   - 🔧 可以改进的(每个问题配代码示例)
   - 💡 建议复习的概念(给 1-2 个资源链接)
5. 最后用 1 句话鼓励学生,强调学习过程

## 输出格式

Markdown,三级标题分三段,代码示例用 fenced code block。
总长度不超过 500 字。

## 不要做

- 不要给分数或评级
- 不要直接修改学生代码
- 不要批评学生本人,只评论代码
- 不要替学生写完整答案

测试你的 Skill

写完后,用 3 种不同问法测试:

  1. 显式触发:

    > /assignment-feedback 帮我看看 student01.py

  2. 隐式触发(贴近真实用户):

    > 这份作业写得怎么样?给点反馈

  3. 边界情况(应该不触发):

    > 帮我写一个新功能

如果第 2 个没自动触发,优化 description。

版本管理

Skill 文件放在 Git 仓库中,跟其他代码一样管理:

git add .claude/skills/
git commit -m "feat: 新增作业初评 skill"

团队共享:把 .claude/ 提交到项目仓库,所有成员自动获得。

高级:多文件 Skill

复杂 Skill 可以引用其他文件:

.claude/skills/assignment-feedback/
├── SKILL.md              # 主入口
├── templates/
│   └── feedback.md       # 输出模板
├── checklists/
│   └── python-quality.md # 检查清单
└── examples/
    └── good-feedback.md  # 范例

在 SKILL.md 中引用:

请参考 `templates/feedback.md` 的格式输出。
请使用 `checklists/python-quality.md` 作为检查清单。

给团队的 Skill 设计建议

  1. 一个 Skill 解决一类问题——别试图一个 Skill 干所有事
  2. 保持单一职责——反馈是反馈,评分是评分,分开
  3. 留可配置项——比如"默认反馈长度 500 字"用环境变量
  4. 写使用文档——在 Skill 文件顶部留 1 段示例

下一步