Claude Agent Skills 完整教程（2026）：SKILL.md、触发规则与测试

先区分三个概念

如果一段说明必须始终生效，放 CLAUDE.md；如果它是一套会重复使用的任务流程，做成 Skill； 如果需要实时数据或外部动作，优先考虑 MCP。一个成熟工作流也可以三者组合。

Skill 的标准目录结构

my-company-pr-review/
├── SKILL.md              # 必需：触发描述与主流程
├── references/           # 可选：规范、API 文档、长示例
│   └── review-rules.md
├── scripts/              # 可选：确定性、可重复执行的脚本
│   └── collect-diff.sh
└── assets/               # 可选：输出要复用的模板、图标、字体
    └── report-template.md

官方写作指南把加载分成三层：名称与描述常驻；Skill 触发后加载 SKILL.md 正文；其他资源按需读取或执行。 这就是“渐进式披露”，它让主文件保持短小，也减少无关上下文。

从零写一个可用的 SKILL.md

---
name: my-company-pr-review
description: Review a pull request against our TypeScript and API conventions. Use when the user asks to review a PR, audit a diff, or check code before merge.
---

# Company PR review

1. Read [references/review-rules.md](references/review-rules.md).
2. Inspect the requested diff. Do not modify files unless the user asks for fixes.
3. Report only actionable findings with file and line references.

## Output

- Verdict: pass / changes requested / blocked
- Findings ordered by severity
- Missing tests
- Residual risks

name 怎么写

使用短、稳定、可读的标识，并让目录名与技能名保持一致。不要把日期、模型版本或一次性项目编号写进名称， 否则内容很快过期。

description 怎么写

description 同时回答两件事：这个 Skill 做什么，以及什么任务应该用它。 “A skill for code review” 太泛；上面示例明确了对象、规范和触发场景，更容易自动调用，也更少误触发。

正文怎么写

• 用祈使句写动作，先给判断规则，再给输出格式。
• 开放性任务给原则；危险或脆弱操作给精确步骤与校验。
• 避免复制 Claude 已经知道的通用知识，把篇幅留给你的专有流程。
• 主文件接近 500 行时继续拆分，并明确说明何时读取哪个参考文件。

在 Claude Code 中安装与共享

当前 Claude Code 会监听已存在的技能目录，大多数编辑可在会话内生效；如果启动时顶层技能目录根本不存在， 新建目录后可能需要重启一次。可以用 /skill-name 直接调用，也可以让 Claude 根据 description 自动判断。

测试：别只看“有没有触发”

为同一 Skill 准备至少三组用例：

1. 应触发：真实用户会怎么描述目标。
2. 不应触发：相邻但不属于该流程的任务。
3. 边界情况：缺文件、空 diff、脚本失败、权限不足。

质量评估要比较启用 Skill 前后的可验证结果，例如遗漏问题数、格式合格率、脚本成功率，而不是只看回答是否更长。 Anthropic 的 skill-creator 也提供了用固定 prompt、期望结果和断言组织 eval 的思路。

安全检查

• 安装第三方 Skill 前，阅读全部 SKILL.md 与 scripts；不要只看名称和介绍。
• 重点检查网络请求、凭证读取、递归删除、上传文件和修改权限的命令。
• allowed-tools 是预授权，不是完整沙箱；真正禁止某类工具要配合权限 deny 规则。
• 项目级 Skill 随代码仓库分发，应像构建脚本一样接受代码审查。
• 脚本输出与网络内容都可能携带提示注入，不要让未验证文本直接决定高风险动作。

常见问题