(自用)skill基础什么是skill 一个skill是一个文件夹, 包含: SKILL.MD (必须): 带有YAML

什么是skill

一个skill是一个文件夹, 包含:

SKILL.MD (必须): 带有YAML前置元数据(frontmatter)的Markdown的指令文档
scripts/ (可选): 可执行代码(Python, Bash)
references/ (可选): 按需加载的文档资料
assets/ (可选): 输出中使用的模板,字体,图标等资源

核心设计原则:

渐进式披露(Progressive Disclosure)

技能采用三级结构:

第一层 (YAML 前置元数据): 始终加载在系统提示词中, 只提供足够的信息, 让Agent知道在什么情况下使用哪个技能, 而无需把全部内容都加载进上下文
第二层 (SKILL.md 正文): 当Agent认为该技能与当前任务相关的时候才会加载, 包含完整的指令和指导
第三层 (链接文件): 技能目录中打包的其他文件, agent仅在需要的时候才会进入, 浏览并且发现

可组合型(Composability)

Agent可以同时加载多个SKILL, 你的SKILL应该与其他的技能良好写作, 而不是默认他是唯一可用的能力

可移植性(Portability)

技能应该在所有的Agent中的表现完全一致, 只要运行环境支持该技能所需的依赖,你创建一次技能, 就可以在所有使用场景中无需修改直接使用

用例

好的用例定义

Use Case: Project Sprint Planning 
Trigger: User says "help me plan this sprint" or "create sprint tasks" 
Steps: 
1. Fetch current project status from Linear (via MCP) 
2. Analyze team velocity and capacity 
3. Suggest task prioritization 
4. Create tasks in Linear with proper labels and estimates Result: Fully planned sprint with tasks created

你需要自问:

用户想要达成什么目标
这需要哪些多步骤的工作流
需要用到哪些工具(内置或MCP)
应该把哪些领域知识或最佳实践沉浸进skill?

常见的skill用例类别

类别1: 文档与资产创建(Document & Asset Creation)

用途: 生成一致,高质量的输出,包括文档,演示文稿,应用,设计稿,代码等真实例子: frontend-design skill (也可以参考docx,pptx,xlsx,和ppt等相关skill) 例如: 创建风格鲜明, 可用于生产环境的前端界面, 具备高质量设计, 用于构建web组件, 页面, 产物, 海报或者应用的时候关键技巧:

内置风格指南与品牌标准
使用模板结构保证输出一致性
在最终输出前进行质量检查,列出清单(checklist)
不需要外部工具-仅使用内置能力

类别2: 工作流自动执行

用途: 适用于需要一致方法论的多步骤流程, 包括跨多个MCP server的协同真实例子: skill-creator skill 例如: 用于创建新技能的交互式指南, 带用户完成用例定义, frontmatter生成, 指令撰写与校验关键技巧:

带校验关卡(validation gates)的逐步工作流
常见结构的模板化
内置审查与改进建议
迭代式优化循环

类别3: mcp增强

用途: 提供工作流知道, 以增强mcp server 所提供的工具访问能力真实例子: sentry-code-review skill 通过他们的mcp server 使用Sentry 的错误监控数据, 自动分析并修复github pull request 中检测到的bug 关键技巧:

串联多个mcp调用并按顺序协调执行
内嵌领域专业知识
补充用户原本需要手动说明的上下文信息
针对常见的mcp问题的错误处理

如果判断你的skill在正常工作

量化指标:

在90%的相关查询上能触发skill
如何衡量: 准备10-20条本应该触发该skill 的测试查询, 记录他自动加载的次数vs需要手动显示调用的次数
在x次工具调用内完成工作流
如何衡量: 对比同一个任务在启用/不启用skill的情况下执行, 统计工具调用次数与消耗的总token数
每个工作流0次失败的api调用
如何衡量: 在此时运行期间监控mcp server日志, 记录重试率与错误码质性指标
用户不需要提示agent下一步该做什么
如何评估: 测试过程中观察你需要多少次纠正方向或澄清下一步了; 也可以向beta用户收集反馈
工作流能完成且不需要用户纠错
如何评估: 对同一请求重复运行3-5次, 比较输出在结构一致性与质量上的表现
跨会话结果一致
如何评估: 新用户在几乎不需要额外知道的情况下, 能否第一次就完成任务

技术要求

文件结构

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
不允许大写 :NotionProjectSetup 不要放 README.md:
不要在skill文件夹里包含README.md
所有文档都放在SKILL.md 或者references/目录下
注意: 如果通过github分发, 你仍然可能需要在仓库根目录提供一个给人看的README

YAML frontmatter: 最重要的部分

必须格式

name: your-skill-name 
description: What it does. Use when user asks to [specific phrases].

需要提供一个你的skill的名字, 他是做什么的描述字段要求:

name 必须:
- 只能用kebab-case 命名
- 不能有空格和大写字幕
- 应该与文件名称一致
description 必须:
- 必须同时包含
  - 这个skill做什么
  - 什么时候用(触发条件
  - 少于1024个字符
- 不能出现xml标签(不能出现<或>
- 要包含用户可能会说的具体任务/表述
- 如相关,请提及文件类型(例如docx,pptx,xlsx
license(可选)
- 如果你要把skill开源, 就使用这个字段
- 常见的取值: MIT, Apache-2.0
compatibility (可选
- 1-500个字符
- 用于说明环境要求, 例如: 目标产品, 需要的系统包, 是否需要网络访问等
metadata(可选
- 可以填写任意自定义的键值对
- 建议字段:author , version ,mcp-server

metadata:
author: ProjectHub
version: 1.0.0
mcp-server: projecthub

安全限制 forbidden in frontmatter 禁止包含:

xml, 尖括号 < >
名称中包含 claude 或者 anthropic 的skill 保留字段原因: frontmatter 会出现在agent的系统提示词中, 若包含恶意内容, 可能会被注入指令, 从而影响系统行为

编写有效的skill

description 字段

这个字段提供了恰到好处的信息 ,使agent能够判断何时应该使用某个skill, 而无需将其全部内容加载到上下文中这是渐进式信息披露progressive disclosure 的第一层机制

结构: [what it does] + [When to use it] + [Key capabilities] 示例

# Good - specific and actionable 
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff". 
# Good - includes trigger phrases description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets". 
# Good - clear value proposition description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

一些不好的示例

# Too vague 
description: Helps with projects. 
# Missing triggers description: Creates sophisticated multi-page documentation systems. 
# Too technical, no user triggers description: Implements the Project entity model with hierarchical relationships.

主要指令

推荐的结构

---
name: your-skill 
description: [...]
--- 
# Your Skill Name 
## Instructions 
### Step 1: [First Major Step] Clear explanation of what happens.

Example: 
```bash python scripts/fetch_data.py --project-id PROJECT_ID 
Expected output: [describe what success looks like]

示例1 用户说设置一个新的营销活动步骤: 1 通过mcp获取现有活动列表 2 使用提供的参数创建新的活动结果: 活动创建成功, 并返回确认连接故障排查错误: [常见错误信息] 原因: [发生原因] 解决方案 [修复方法]

最佳实践

Run `python scripts/validate.py --input {filename}` to check data format. 
If validation fails, common issues include: 
- Missing required fields (add them to the CSV) 
- Invalid date formats (use YYYY-MM-DD)

错误的示例

Validate the data before proceeding.

包含错误的实例

# Common Issues 
### MCP Connection Failed 
If you see "Connection refused": 
1. Verify MCP server is running: Check Settings > Extensions 
2. Confirm API key is valid 
3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect

包含引用的实例

Before writing queries, consult `references/api-patterns.md` 
for: - Rate limiting guidance 
- Pagination patterns 
- Error codes and handling

使用渐进式的信息披露保持 SKILL.md 只包含核心指令, 将详细文档移动到references/目录, 并在文中进行链接

测试与迭代

根据需求不同, Skill 可以采样不同严格程度的测试方式

在Claude.ai 中进行手动测试, 直接运行查询并观察行为, 迭代速度快, 无需额外的配置
在claude code 中进行脚本化测试 : 自动化测试用例, 实现跨版本变更的可重复验证
通过skills api 进行程序化测试 -- 构建评估套件, 针对定义好的测试集进行系统化运行选择与质量要求和skill可见性相匹配的测试方式, 一个仅供小团队内部使用的skill 与面向数千名企业用户部署的skill , 其测试需求显然不同实用建议: 先围绕单一任务进行迭代, 然后在扩展我们发现, 高效的skill 创建者通常会针对一个挑战性的单一任务反复迭代, 直到claude成功完成, 然后将验证有效的方法提炼为一个skill, 这种方式利用了claude的上下文学习能力, 相比大范围测试能更快获得有效反馈, 在打好基础后, 在扩展到多个测试用例以提升覆盖率

使用skill-creator skill

可以帮助构建和迭代skill, 如果你已经有mcp服务器, 并且明确了2-3个核心工作流, 通常可以在一次会话中完成一个可用skill的构建与测试-- 通常只需要15-30分钟创建skill:

从自然语言描述生成skill
生成包含frontmatter的规范格式SKILL.md
建议触发短语与结构设计

审查skill

标记常见问题(如描述过于模糊, 缺少触发条件, 结构问题
识别潜在的过度触发或触发不足风险
根据skill的目标用途建议测试用力

迭代改进

在使用skill并遇到边界情况或失败案例后, 将这些示例返回给skill-creator
示例: 基于本次对话中识别的问题与解决方案, 改进该skill 对特定便捷情况的处理方式

use the skill-creatro skill to help me build a skill for [you use case]

基于反馈进行迭代

skill 是持续演进的文档, 应根据实际使用情况不断优化触发不足的信号

在应当触发的时候未被加载
用户需要手动启用
出现关于何时使用该skill的支持类问题

解决方案: 在description 中增加更多细节与语义分析, 必要的时候补充关键技术术语, 以增强触发准确性

过度触发的信号:

在无关查询中被加载
用户主动禁用
用户对skill的用途产生困惑

解决方案: 添加负触发条件, 并收窄描述范围, 使触发条件更加具体

执行问题:

结果不一致
api调用失败
需要用户进行纠正

解决方案: 优化指令内容, 补充错误处理逻辑

分发与共享

个人获取skill的方式

下载skill文件夹
如果有需要, 将文件夹压缩为zip
在claude.ai 中通过settings > Capabilities > Skills 上传
或放置在claude code 的skills目录中

当前推荐的做法

建议首先将你的skill托管在github的公开仓库中, 提供清洗的readme (面向人类读着--注意, 该readme应该位于仓库根目录, 而不是skill文件夹内部, skill文件夹中不应包含readme.md , 随后, 在你的mcp文档中新增一个章节, 链接到skill , 说明两者结合使用的价值, 并且提供快速上手指南

托管到github

为开源skill创建公开仓库
提供清洗的readme, 包含安装说明
提供示例用法与截图

在你的mcp仓库中进行文档说明

在mcp文档中链接到对应的skill
说明两者结合使用的价值
提供快速上手指南

创建安装指南

# Installing the [Your Service] skill 
1. Download the skill: 
    - Clone repo: `git clone https: /github.com/yourcompany/ skills` 
    - Or download ZIP from Releases 
2. Install in Claude: 
    - Open Claude.ai > Settings > skills 
    - Click "Upload skill"
    - Select the skill folder (zipped) 
3. Enable the skill: 
    - Toggle on the [Your Service] skill 
    - Ensure your MCP server is connected 
4. Test: 
    - Ask Claude: "Set up a new project in [Your Service]"

skill的定位

你如何描述的你的skill, 将直接决定用户是否理解其价值, 并真正尝试使用他, 在readme,文档或者营销材料中介绍skill的时候, 应该注意以下原则聚焦结果, 而非功能细节: 好的示例:

ProjectHub skill 可以让团队在几秒钟内完成完整项目工作区的搭建——包括页面、数据库和模板——而不再需要花费 30 分钟进行手动配置

不好的示例

ProjectHub skill 是一个包含 YAML frontmatter 和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。

强调mcp与skill的协同价值

我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。  
我们的 Skill 教会 Claude 你团队的冲刺规划流程。  
两者结合，实现 AI 驱动的项目管理。

模式与故障排查

这些patterns 来源于早期采用者的内部团队创建的skill实践经验, 他们代表的是被验证有效的常见方法, 而不是强制性的模板选择你的方式: 问题驱动vs工具驱动可以把他类比为去建材商店, 你可能戴着一个问题进去 -- 我uyao修理厨房橱柜, 然后工作人员为你推荐合适的工具, 也可能是你先选了一把新的电钻, 在询问如何将他用于具体任务

skill的工作方式类似

问题驱动problem-first 我需要搭建一个项目工作区-> 你的skill按正确顺序编排合适的mcp调用, 用户描述的是结果目标; skill负责调用工具
工具驱动 tool-first
我已经连接了notion mcp -> 你的skill教会claude 最优工具流与最佳实践, 用户已经具备工具访问能力, skill提供专业方法论

大多数skill会偏向其中一种方向, 明确哪种定位更符合你的使用场景, 有助于你在下文选择合适的设计模式

模式1 : 顺序式工作流编排

适用场景: 用户需要按照特定顺序执行多步骤流程示例结构

## workflow : onboard new Customer 
### Step 1 : Create Account 
Call MCP tool : `create_customer`
Parameters : name , email , company 
### Step2 : Setup payment 
Call mcp tool : `setup_payment_method`
Wait for: payment method verification 
### Step3 : Create Subscription
Call mc tool : `create_subscription`
Parameters: plan_id, customer_id (from Step 1)
### Step 4: Send Welcome Email 
Call MCP too: `send_email`
Template: welcome_email_template

关键技巧:

明确步骤顺序
定义步骤之间的依赖关系
在每个阶段进行校验
为失败情况提供回滚指令

模式2: 多MCP 协同编排

适用场景: 工作流设计多个服务, 需要跨系统写作示例: 设计到开发的交接流程

### Phase 1 : Design Export (Figma MCP)
1. Export design assest from Figma 
2. Generate design specifications 
3. Create asset manifest 
### Phase 2 : Asset Storage (Drive MCP
1. Create project folder in Drive 
2. Upload all assets 
3. Generate shareable links
### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks 
3. Assign to engineering team 
### Phase 4: Notification 
1. Post handoff summary to #engineering 
2. Include asset links and taks refernces

关键技巧: 明确阶段划分在不同的mcp之间传递数据在进入下一阶段前进行验证集中式错误处理机制

模式3: 迭代式优化

使用场景: 输出质量可以通过多轮迭代不断提升示例: 报告生成流程

## iterative report creation
### initial Draft 
1. Fetch data via mcp
2. Generate first draft report 
3. save to temporary file 
### Quality Check 
1. Run validation script : `scripts/check_report.py`
2. Identify issues:
    - Missig sessions 
    - Inconsistent formatting
    - Data validation errors 
### Refinement loop
1. Address each identified issue 
2. Regenerate affected sections 
3. Re-validate
4. Repeat untial quality threshold met 
### Finalization 
1. Apply final formating 
2. Generate summary 
3. save final version

明确质量评判标准采用迭代式改进机制使用校验脚本辅助验证明确合适停止迭代

模式4 : 基于上下文的工具选择

使用场景: 目标结果相同, 但是根据不同上下文需要调用不同工具示例: 智能文件存储

## Smart file storage 
### Decision Tree
1. check file type and size 
2. Determine best storage location :
    - large files (>10mb): use cloud storage MCP
    - collaborative docs: use Notion/Docs MCP
    - Code files : use Github mcp
    - Temporary files : Use local storage 
### EExecute Storage 
Base on descision:
- Call appropriate mcp tool
- Apply service-specific metadata 
- Generate access link
### Provide Context to user 
Explain why that storage was chosen