前言

如果你已经会写 Prompt，但总觉得“同样的事每次都要重新说一遍”，那你需要的不是更长的 Prompt，而是 Skills。
一句话理解：

Skill = 可复用、可触发、可迭代的 AI 工作 SOP。

它把“某类任务怎么做才专业”封装进一个标准文件夹里，让 Claude 在合适的时候自动调用。

一、Skills 到底解决了什么问题？

传统 Prompt 的痛点：

• 每次重复描述流程
• 结果稳定性依赖临场发挥
• 长上下文浪费 token
• 多人协作时风格难统一

Skills 的优势：

• 一次定义，反复复用
• 自动触发 + 手动调用都支持
• 渐进式加载（只在需要时加载详细说明）
• 团队可共享、可版本化、可持续优化

对比项	普通 Prompt	Skill 机制
复用成本	每次重写	一次编写长期复用
上下文成本	常常整段硬塞	分层按需加载
一致性	看提问质量	由固定流程保障
团队协作	口口相传	文件化沉淀
演进方式	Prompt 版本难管理	直接迭代 SKILL.md 与资源目录

二、Skills、Rules、MCP 分工

• Rules / Memory：约束“行为与偏好”（语气、格式、禁忌）
• MCP / Tools：提供“能力接口”（API、数据库、第三方系统）
• Skills：定义“怎么把能力用对、用顺、用稳定”

可以把它理解为：

• MCP 是厨房和设备；
• Skills 是菜谱和出品标准。

两者结合，才是能落地的 Agent 工作流。

三、官方推荐的 Skill 结构

最小可用结构：

my-skill/
└── SKILL.md

完整推荐结构：

my-skill/
├── SKILL.md          # 必需
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、素材

渐进式加载的三层机制

1. Frontmatter 层（常驻）：只加载 name、description 等识别信息
2. SKILL.md 正文层（按需）：任务相关时加载详细流程
3. 目录资源层（按需）：只有引用到时才读取 references/、scripts/ 等

这就是 Skills 在“强能力 + 省 token”之间取得平衡的关键。

description决定Skills触发率

官方指南反复强调：Skill 是否会被自动加载，最关键看 description。

高质量描述公式：

做什么 + 何时用 + 用户会怎么说（触发短语）

好例子：

description: 管理 Linear 冲刺规划与任务创建。用于用户提到“sprint 规划”、“创建任务”、“项目排期”时。

坏例子（过泛）：

description: 帮助处理项目。

坏例子（纯技术无用户语言）：

description: 实现层次化 Project 实体关系模型。

SKILL.md 结构

必填字段：

name: skill-name
description: 做什么、何时使用，包含具体触发表述

字段规则：

• name：必须 kebab-case（小写字母/数字/连字符）
• description：必填，建议写清触发场景，最长 1024 字符
• license / compatibility / metadata / allowed-tools：可选

官方限制（非常重要）：

• 文件名必须是 SKILL.md（大小写敏感）
• 不要在 skill 文件夹里放 README.md（说明文档放 references/ 或仓库根目录）
• name 不能包含保留前缀（如 claude、anthropic）
• Frontmatter 中禁止使用 < >

四、Skills通用模板

name: python-naming-standard
description: 统一 Python 内部函数命名规范。用于用户要求编写、重构、审查 Python 代码时。
metadata:
  author: your-name
  version: 1.0.0

# Python 内部命名规范

## 使用时机
- 用户要求写/改/审查 Python 代码
- 涉及内部辅助函数命名一致性

## 执行步骤
1. 识别内部辅助函数
2. 检查是否以 `_internal_` 前缀命名
3. 若不符合，给出最小改动建议
4. 输出修改建议与原因

## 错误处理
- 若项目已有明确命名规范，优先遵循项目规范并说明冲突点

## 参考
- 命名示例见 `references/naming-examples.md`

什么时候要把内容拆到 references/ 和 scripts/？

官方建议：SKILL.md 保持“短而清晰”，详细内容拆出去。

• 规则太多：放 references/*.md
• 需要确定性校验：放 scripts/*.py
• 输出模板固定：放 assets/*.md

示例引用写法：

在处理 API 分页前，先参考 `references/api-patterns.md`。
如需校验输入数据，执行 `python scripts/validate.py --input {filename}`。

五、Skills测试

1) 触发测试

• 应该触发：直接表述 + 同义改写
• 不该触发：无关任务

2) 功能测试

• 输出是否正确
• 工具调用是否成功
• 异常分支是否可恢复

3) 性能对比

/status

• 与“无 Skill”相比，是否减少往返轮次、失败调用、token 消耗

一个很实用的标准：先打磨一个最难任务直到稳定，再扩展测试集。

六、典型故障排查（你大概率会遇到）

问题 1：Skill 不触发

• 原因：description 太泛、没有用户语言触发词
• 解决：补充“用户会怎么说”的表述

问题 2：Skill 过度触发

• 原因：描述范围过大
• 解决：增加边界条件和负向约束（Do NOT use for …）

问题 3：触发了但执行不稳

• 原因：正文太啰嗦、关键步骤埋太深、指令含糊
• 解决：关键步骤前置，流程编号，错误处理明确

问题 4：MCP 调用失败

• 原因：连接状态、鉴权、工具名大小写、参数校验
• 解决：把校验逻辑写成脚本，减少语言歧义

七、参考资料

• Anthropic 官方 Skills 仓库：https://github.com/anthropics/skills
• The Complete Guide to Building Skill for Claude（PDF）：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en
• Anthropic 工程文章（Skills + MCP）：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Agent Skills 标准站点：https://agentskills.io
• VS Code Copilot Agent Skills：https://code.visualstudio.com/docs/copilot/customization/agent-skills

如果你只记住一句话：

写 Skill 的本质，不是堆指令，而是沉淀你团队的“SOP”。