Agent Skills 实战：用 SKILL.md 把 Claude Code 从助手变成队友

前言

今天 HN 上 Addy Osmani 的「Agent Skills」拿了 162 票，GitHub Trending 前十里有七个跟 Agent 相关------ruflo 2598 星、TradingAgents 2182 星、browserbase/skills 320 星、jcode 548 星。Agent 工具正在从"一个模型干活"变成"多个 Agent 协作"。

但大部分人用 Agent 的方式还停留在 2024 年------打开终端，说一句"帮我写个函数"，看着它吐代码。这不是 Agent 的正确用法。

这篇文章讲的是 Agent Skills 机制------怎么用 SKILL.md 文件让 Claude Code 从"一次性问答工具"变成"懂你的项目的长期队友"。所有代码在 Claude Code + Claude Opus 4.5 下验证通过。

一、什么是 Agent Skills

Agent Skills 本质上是一段 Markdown 格式的上下文注入。当你对 Claude Code 说 /tdd，它读的是 tdd.md 文件里的指令------不是模型本身的能力，是外部注入的约束和流程。

objectivec 复制代码

你: "帮我修复 payment.py 的并发 bug"

没有 SKILL.md:
  AI 直接改代码 → 可能引入新 bug → 没有测试 → 你手动验证

有 SKILL.md:
  AI 读 skill 文件 → 先写测试 → 跑测试确认复现 → 改代码 → 
  再跑测试 → 通过才提交 → 生成 commit message

区别不是模型能力，是流程约束。模型一样，但加了约束的模型做的决策质量完全不一样。

二、写一个可用的 SKILL.md

下面是我用来做 TDD 的 skill 文件，简化自 obra/superpowers 仓库（GitHub 4 万星）：

markdown 复制代码

// skills/tdd.md
# TDD Workflow

## Trigger
When the user asks to "fix a bug" or "add a feature", follow this workflow.

## Workflow
1. Write a failing test that reproduces the bug or defines the feature
2. Run the test and confirm it FAILS
3. Write the minimal code to make the test pass
4. Run the test and confirm it PASSES
5. Refactor: improve code structure without changing behavior
6. Run all tests to ensure no regression

## Commit Message Format
Generate commit messages in this format:
<type>: <description>

Where type is one of: feat, fix, refactor, test, docs

## Anti-patterns (DO NOT)
- Do NOT modify the test to fit broken code
- Do NOT skip step 2 or step 4
- Do NOT commit until all tests pass

保存到 .claude/skills/tdd.md。然后在 Claude Code 里执行 /tdd。

这个文件的含金量在最后一段「Anti-patterns」。没有它，AI 在遇到困难时会走捷径------改测试而不是修代码、跳过验证步骤。Anti-patterns 就是 guardrails。

三、多 Skill 组合

单个 skill 解决单个问题，多个 skill 组合才是 Agent 编排的本质。下面是我项目中同时生效的三个 skills：

markdown 复制代码

// skills/code-review.md
# Code Review Workflow
## Trigger
After any code change, review against this checklist.
## Checklist
- [ ] Functions < 50 lines
- [ ] No hardcoded secrets
- [ ] Error handling explicit
- [ ] New code has tests
## Output
Mark each item as PASS or FAIL. For FAIL items, suggest the fix.

markdown 复制代码

// skills/debug.md
# Systematic Debugging
## Workflow
1. Reproduce: Write exact steps to trigger the bug
2. Isolate: Find the minimum input that causes failure
3. Hypothesize: State what you think is wrong BEFORE touching code
4. Test hypothesis: Add logging, not fixes
5. Fix: Only after confirming the hypothesis
## Rule
Never skip from step 1 to step 5.

三个 skills 同时加载后，Claude Code 的行为变成了：

写代码 → 自动触发 code-review skill
遇到 bug → 自动触发 debug skill
做新功能 → 自动触发 tdd skill

这不是三个独立的功能，是三个 skill 在同一个 session 里叠加生效。

四、踩坑记录

写了十几个 skill 文件后，踩过的坑：

坑 1：Skill 太长，模型跳过关键步骤

第一个版本的 tdd.md 写了 200 多行，包含各种边界情况。结果 Claude Code 经常跳过步骤 2（确认测试失败）。把 skill 缩短到 30 行以内，关键步骤用 ### Anti-patterns 明确标注后，跳过率从 30% 降到接近零。

教训：Skill 不是文档，是指令。越短越精准。

坑 2：Skill 之间冲突

同时加载 tdd.md 和 code-review.md 时，两个 skill 都在代码修改后触发------tdd 要求"立即可重构"，code-review 要求"先过 checklist"。结果是 AI 在重构和 review 之间来回跳，无限循环。

修复方法是在每个 skill 头部加 Priority 和 After 字段：

markdown 复制代码

// skills/tdd.md
# TDD Workflow
## Priority: 1
## After: code-review

这样确定了执行顺序：先 code-review → 再 tdd refactor。

坑 3：Skill 中写死路径

早期版本里写的是 cd /home/user/project && pytest tests/。换台机器就炸。改成相对路径和通用命令：

bash 复制代码

# 好
pytest tests/ -x

# 坏
cd /home/user/project && pytest tests/test_payment.py -x

五、跟 GitHub 上的趋势对一下

今天 GitHub 上最火的 Agent 项目是 ruflo（2598 星），做的是 Agent 编排------把多个 skill 文件 + 多个子 Agent 组合成一个工作流。本质上就是把上面手动组合的 tdd + code-review + debug 三个 skill，用工具自动调度。

browserbase/skills（320 星）更进一步------把 Claude Agent SDK 和浏览器操作绑在一起，你的 skill 不光能操作代码，还能操作网页。比如一个 skill 写"打开 GitHub，找到 trending 页，截取前 5 个项目的 star 数"------它真的能做到。

总结

Agent Skills 不是新技术，是 LLM 的 prompt engineering 被标准化成文件了。但标准化的意义很大------以前你得每次手动写 prompt，现在下个 .md 文件放项目里，整个团队共享同一套约束。

如果你的团队用 Claude Code，先从写一个 tdd.md 开始。一个 30 行的 skill 文件，比你写 300 行的 code review 文档效果好十倍。

代码地址：

obra/superpowers: github.com/obra/superp...
Claude Code skills 文档: docs.anthropic.com/en/docs/cla...
本文所有 skill 文件可在 GitHub 找到完整版本