Anthropic官方Claude_Skills构建指南完整版（上）-基础知识与规划设计-weelinking中转服务

🔴🔴 国内丝滑使用 Claude？ 👉 weelinking 大模型中转服务，全系模型支持，按量付费，赠送Claude测试额度 👈

摘要：Anthropic发布官方33页Claude Skills构建指南，本文为全文中文译版上篇，涵盖Skills基础知识与规划设计两大章节。详解Skill文件夹结构、YAML前置信息规范、渐进式披露/可组合性/可移植性三大核心设计理念，以及MCP增强型Skill工作流的最佳实践。包含文档与素材创建、工作流自动化、MCP增强三类典型用例解析，手把手教你写出精准触发、格式规范、指令清晰的高质量Skill。国内开发者可通过weelinking中转服务稳定访问Claude全系模型，快速落地AI工作流自动化。

关键词：Claude Skills教程、Claude Skill构建指南、SKILL.md写法、Claude Skill YAML、MCP技能开发、Claude工作流自动化、weelinking中转服务、Claude国内使用、Anthropic官方指南、AI Agent技能

📋 段落导航

序号	章节	内容概要
一	简介：为什么需要Skill	Skill定义、适用场景与阅读路径
二	第一章：基础知识	Skill文件结构、三大核心设计理念
三	面向MCP开发者：用Skill增强MCP	MCP连接层与Skill知识层的配合原理
四	第二章：规划与设计——从用例出发	三类常见用例详解与用例定义模板
五	技术要求：文件夹结构与命名规范	必须遵守的命名规则与YAML规范
六	写好description字段与主体指令	好坏写法对比、指令结构与最佳实践
七	其他文章推荐	相关往期好文链接

🔴 🔴 国内丝滑使用 Claude？ 👉 weelinking 大模型中转服务，全系模型支持，按量付费，赠送Claude测试额度 👈

一、简介：为什么需要Skill

技能（Skill）其实就是一套指令——打包成一个简单的文件夹——用来教 Claude 怎么处理特定任务或工作流程。这是你自定义 Claude 最有力的方式之一。

你有没有遇到过这种情况：每次跟 Claude 对话，都要重新解释你的偏好、流程和专业背景？有了技能，你只需要教一次，以后每次都能直接用上。

什么时候用技能最合适？ 就是当你有可以重复执行的工作流程时，比如：

根据设计稿生成前端界面
用固定的方法论做研究调查
按照团队风格指南写文档
协调多个步骤的复杂流程

技能跟 Claude 的内置功能（比如执行代码、创建文档）搭配起来效果很好。如果你在做 MCP 集成，技能还能帮你把原始的工具访问能力，变成可靠、顺畅的工作流程。

读完��份指南，你会学到：

技能的技术要求和最佳实践
独立技能和 MCP 增强型工作流的设计模式
我们观察到的那些真正有效的做法
怎么测试、迭代、发布你的技能

两条阅读路径

只做独立技能？ 重点看"基础知识"和"规划与设计"部分。

想在 MCP 上叠加技能？ "技能 + MCP"和第五章的设计模式更适合你。

两条路径用的是同样的技术规范，按自己的需求选就好。

预计投入：读完这份指南后，配合 skill-creator 工具，通常 15-30 分钟就能做出你第一个能用的技能。

二、第一章：基础知识

技能到底是什么？

技能就是一个文件夹，里面放着：

文件/文件夹	是否必须	作用
SKILL.md	✅ 必须	带 YAML 前置信息的 Markdown 格式指令
scripts/	可选	可执行代码（Python、Bash 等）
references/	可选	按需加载的参考文档
assets/	可选	输出用的模板、字体、图标等

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

技能用三层结构来组织内容：

第一层（YAML 前置信息）：每次都会加载到 Claude 的系统提示里。内容要精简——让 Claude 知道"这个技能是做什么的、什么时候该用它"就够了，不需要把所有东西都塞进来。
第二层（SKILL.md 正文）：当 Claude 觉得当前任务跟这个技能有关，才会加载完整指令。
第三层（链接文件）：放在技能文件夹里的其他文件，Claude 可以按需查阅。

这种分层设计的好处：既省 token，又能保留足够的专业深度。

2. 可组合性（Composability）

Claude 可以同时加载多个技能。你的技能要能跟其他技能和平共处，别假设自己是唯一被启用的那个。

3. 可移植性（Portability）

在 Claude.ai、Claude Code 和 API 里，技能的工作方式完全一样。写一次，到处能用——前提是运行环境支持技能所需的依赖。

三、面向MCP开发者：用Skill增强MCP

💡 只做独立技能、不涉及 MCP？可以直接跳到第四节，随时回来看这节。

如果你已经有了运行中的 MCP 服务器，最难的部分其实已经搞定了。技能就是在上面加一层"知识层"——把你已经知道的工作流程和最佳实践固化下来，让 Claude 能够一致地应用它们。

这两者怎么配合？

	MCP（连接层）	技能（知识层）
作用	把 Claude 连接到你的服务（Notion、Asana、Linear 等）	教 Claude 怎么有效地使用这些服务
能力	提供实时数据访问和工具调用能力	固化工作流程和最佳实践
回答	Claude 能做什么	Claude 应该怎么做

没有技能时，用户可能遇到的问题：

连上了 MCP，但不知道下一步该咋办
不断发来"怎么用你的集成做 X"的支持提问
每次对话从头开始，结果每次都不一样
用户会把问题归咎于你的 MCP 连接器，但根本原因其实是缺少工作流程指引

有了技能之后：

预置的工作流程在需要时自动激活
工具调用稳定可靠
最佳实践内嵌在每次交互里
新用户的学习成本大幅降低

四、第二章：规划与设计——从用例出发

在写任何代码之前，先想清楚你的技能要解决的 2-3 个具体场景。

一个好的用例定义长这样：

用例：项目冲刺规划

触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务"

步骤：
  1. 通过 MCP 获取 Linear 的当前项目状态
  2. 分析团队速度和容量
  3. 建议任务优先级
  4. 在 Linear 里创建带标签和估算的任务

结果：冲刺计划规划完毕，任务全部创建好

问自己这几个问题：

用户想达成什么目标？
这需要哪些多步骤的工作流程？
需要哪些工具（Claude 内置的，还是 MCP 的）？
需要嵌入哪些领域知识或最佳实践？

三类常见用例

Anthropic 观察到三种最常见的技能使用场景：

第 1 类：文档和素材创建

适合场景：创建一致的高质量输出，比如文档、演示文稿、应用、设计、代码等。

真实案例：frontend-design 技能
"创建有辨识度的、生产级别的前端界面，注重设计质量。在构建 Web 组件、页面、作品、海报或应用时使用。"

关键做法：

嵌入风格指南和品牌规范
用模板结构保证输出一致
最终确认前做质量清单检查
不需要外部工具——用 Claude 的内置能力就够

第 2 类：工作流程自动化

适合场景：多步骤流程，需要一致的执行方式，可能跨多个 MCP 服务器协调。

真实案例：skill-creator 技能
"创建新技能的交互式向导。引导用户完成用例定义、前置信息生成、指令撰写和验证。"

关键做法：

带验证节点的分步工作流
常见结构的模板
内置审查和改进建议
迭代优化循环

第 3 类：MCP 增强

适合场景：为 MCP 服务器的工具访问能力加上工作流程引导。

真实案例：来自 Sentry 的 sentry-code-review 技能
"利用 Sentry 错误监控数据，通过其 MCP 服务器自动分析和修复 GitHub Pull Requests 中发现的 bug。"

关键做法：

按顺序协调多个 MCP 调用
嵌入领域专业知识
提供用户本来需要手动指定的上下文
处理常见 MCP 问题

定义成功标准

怎么知道你的技能跑通了？先说清楚。下面这些是参考目标，不是死板的门槛——测试时还是需要一定的感性判断。

量化指标：

技能在 90% 的相关查询中触发
- 怎么测：跑 10-20 个应该触发技能的测试问题，记录自动加载的次数
工作流程在 X 次工具调用内完成
- 怎么测：有无技能各跑一次相同任务，对比工具调用次数和 token 消耗
每个工作流程 0 次 API 调用失败
- 怎么测：测试期间监控 MCP 服务器日志，追踪重试率和错误码

定性指标：

用户不需要提示 Claude 下一步该做什么
工作流程无需用户纠正就能跑完
跨会话结果保持一致

五、技术要求：文件夹结构与命名规范

文件夹结构

your-skill-name/
├── SKILL.md              # 必须——主技能文件
├── scripts/              # 可选——可执行代码
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选——参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选——模板等资源
    └── report-template.md

几条必须遵守的规则

SKILL.md 命名：

必须精确写成 SKILL.md（区分大小写）
任何变体都不行：SKILL.MD、skill.md 都不能用

技能文件夹命名：

✅ 用 kebab-case（短横线连接小写）：notion-project-setup
❌ 不能有空格：Notion Project Setup
❌ 不能用下划线：notion_project_setup
❌ 不能有大写：NotionProjectSetup

不要放 README.md：

技能文件夹内别放 README.md
所有文档放在 SKILL.md 或 references/ 里
注意：通过 GitHub 发布时，仓库根目录仍然需要 README 供人类查阅——这和技能文件夹是两回事

YAML 前置信息：最关键的部分

YAML 前置信息是 Claude 决定要不要加载你的技能的依据，务必写对。

最简格式（够用了）：

---
name: your-skill-name
description: 它干什么。当用户说[具体短语]时使用。
---

各字段说明：

name（必填）：

只能用 kebab-case
没有空格，没有大写
最好和文件夹名一致

description（必填）：

必须同时包含：这个技能能做什么 + 什么时候该用（触发条件）
最多 1024 个字符
不能含 XML 标签（< 或 >）
要包含用户可能实际说出的话
如果涉及特定文件类型，要提到

完整字段示例：

---
name: skill-name
description: [必填描述]
license: MIT                                       # 可选：开源协议，如 MIT 或 Apache-2.0
compatibility: Requires Claude.ai with internet    # 可选：环境要求（1-500字符）
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
metadata:
  author: 公司名称
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: support@example.com
---

安全限制：

禁止用 XML 尖括号（< >）
技能名称不能以 "claude" 或 "anthropic" 开头（保留词）
原因：前置信息会进入 Claude 的系统提示，恶意内容可能被用来注入指令

六、写好description字段与主体指令

description 字段写法

Anthropic 工程博客说过："这段元数据……提供了恰好足够让 Claude 知道该用哪个技能的信息，而不需要把所有内容都加载到上下文里。"

这就是渐进式披露的第一层。

格式模板： [能做什么] + [什么时候用] + [主要功能]

✅ 好的写法：

# 好——具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。
  当用户上传 .fig 文件，或者问"设计规格"、"组件文档"、
  "设计转代码交接"时使用。

# 好——包含触发词
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。
  当用户提到"冲刺"、"Linear 任务"、"项目规划"，
  或者要求"创建工单"时使用。

# 好——价值主张清晰
description: PayFlow 的端到端客户引导工作流。
  处理账户创建、支付设置和订阅管理。
  当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

❌ 不好的写法：

# 太模糊
description: 帮助处理项目。

# 没有触发条件
description: 创建复杂的多页文档系统。

# 太技术化，用户不会这么说
description: 实现具有层次关系的 Project 实体模型。

写主体指令

过了 YAML 前置信息，就用 Markdown 写具体的指令。

推荐结构：

---
name: your-skill
description: [...]
---

# 你的技能名称

## 指令

### 第 1 步：[第一个主要步骤]
清楚说明这步要做什么。

示例：
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功时应该看到什么]

第 2 步：[下一步骤，按需添加]

示例

示例 1：[常见场景]

用户说："设置一个新的营销活动"
操作：

通过 MCP 获取现有活动
用提供的参数创建新活动
结果：活动创建成功，附上确认链接

故障排查

错误：[常见错误消息]
原因：[为什么会出现]
解决方法：[怎么修]

**写指令的最佳实践：**

✅ **要具体，要说清楚怎么操作：**

运行 python scripts/validate.py --input {filename} 来检查数据格式。
如果验证失败，常见原因有：

缺少必填字段（把它加到 CSV 里）
日期格式不对（要用 YYYY-MM-DD）

❌ **别含糊其词：**

继续之前请先验证数据。

✅ **要包含错误处理：**
```markdown
## 常见问题

### MCP 连接失败
看到 "Connection refused" 时：
1. 确认 MCP 服务器在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重连：设置 > 扩展 > [你的服务] > 重新连接

✅ 要用渐进式引用：

写查询之前，请先看 `references/api-patterns.md`，里面有：
- 速率限制指南
- 分页模式
- 错误码和处理方式

SKILL.md 要保持聚焦：核心指令放在 SKILL.md，详细文档移到 references/ 里，通过链接引用。

📌 下篇预告：第40篇将继续翻译官方指南后半部分，涵盖测试与迭代、发布与分享、五大设计模式、完整故障排查手册以及快速检查清单。敬请关注！

🔴 🔴 国内丝滑使用 Claude？ 👉 本文全系使用 weelinking，全系模型支持 👈

posted @ 2026-03-08 15:33 搬石头的马农阅读(5) 评论(0) 收藏举报

刷新页面返回顶部

weelinking

Anthropic官方Claude_Skills构建指南完整版（上）-基础知识与规划设计-weelinking中转服务

📋 段落导航

一、简介：为什么需要Skill

两条阅读路径

二、第一章：基础知识

技能到底是什么？

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

2. 可组合性（Composability）

3. 可移植性（Portability）

三、面向MCP开发者：用Skill增强MCP

四、第二章：规划与设计——从用例出发

三类常见用例

第 1 类：文档和素材创建

第 2 类：工作流程自动化

第 3 类：MCP 增强

定义成功标准

五、技术要求：文件夹结构与命名规范

文件夹结构

几条必须遵守的规则

YAML 前置信息：最关键的部分

六、写好description字段与主体指令

description 字段写法

写主体指令

第 2 步：[下一步骤，按需添加]

示例

示例 1：[常见场景]

故障排查

公告