Claude Skills 入门：从 SKILL.md 规范到写出第一个技能包

如果 MCP 解决的是「Agent 能调用什么工具」，那么 Skill 解决的是「Agent 知道怎么做事」。一个 Skill 就是一份结构化的说明书，告诉 Agent 在特定场景下应遵循什么流程、使用哪些脚本与资料。

Skill 的目录结构

一个最小的 Skill 就是一个文件夹，核心是 SKILL.md：

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行脚本
│   └── convert.py
└── references/       # 可选：参考文档
    └── api-notes.md

SKILL.md 怎么写

文件由 YAML 前言 + Markdown 正文组成：

---
name: my-skill
description: 处理 XX 文件转换的技能。当用户需要
  转换 XX 格式时使用。
---

# 工作流程

1. 先检查输入文件的格式与编码
2. 调用 scripts/convert.py 进行转换
3. 校验输出，失败时报告具体原因

## 注意事项

- 超过 100MB 的文件分批处理
- 输出统一使用 UTF-8

三个要点：

• description 写「什么时候用」：Agent 靠它判断是否加载该 Skill，必须包含触发场景的关键词；
• 正文写「一步步怎么做」：把操作经验拆成可执行的编号步骤，而不是形容词；
• 复杂逻辑放进脚本：Markdown 指挥流程，脚本负责脏活，这比堆文字指令可靠得多。

学习范本

读 Anthropic 官方的 anthropics/skills 仓库最快上手：里面有 docx/pptx/xlsx/pdf 处理的完整实现。注意观察它们如何把「大量格式规则」放进 references、把「确定性操作」放进 scripts——这就是高质量 Skill 的通用套路。

发布与分享

Skill 本质就是 Git 仓库，推送到 GitHub 即可分享。可以给 Awesome Claude Skills 清单提 PR，也欢迎向本站提交收录。

本文基于公开文档整理，规范细节以官方仓库最新说明为准。