大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



技能（skill）是一组指令文件夹，用于教会Claude处理特定任务或工作流程，是定制Claude以满足特定需求的高效方式，可避免重复解释偏好、流程和专业知识，只需教授一次即可持续受益。

技能在可重复工作流程中作用突出（如前端设计生成、规范研究、文档创建等），可与Claude内置功能配合，同时能为MCP集成者提供助力，将工具访问转化为优化的工作流程。对于那些构建 MCP 集成的人来说，技能又增加了一层强大的功能，帮助将原始工具访问转变为可靠、优化的工作流程。

本指南涵盖构建有效技能的全流程（规划、结构、测试、分发），包含实用模式和真实案例，适用于为自身、团队或社区构建技能的场景。

你将从本指南中获得什么： 到最后，你将能够在一个会话中构建一个功能完整的技能。预计使用技能创建器构建和测试你的第一个可用技能大约需要 15-30 分钟。

Skill是具备固定目录结构的文件夹，是Claude的能力扩展载体，其目录包含必需文件和可选文件两类：

• 必需：SKILL.md（带YAML前置元数据的Markdown格式说明文档）
• 可选：scripts/（Python、Bash等可执行代码）、references/（按需加载的文档）、assets/（输出用模板、字体、图标等）

Skill的设计遵循三大核心原则，保障其在Claude生态中高效、兼容、通用的运行特性。

1. 渐进式披露 (Progressive Disclosure)

核心是分级加载，通过三级系统在保证专业性的同时最小化token消耗，是Skill最核心的设计逻辑：

• 第一级（YAML前置元数据）：永久加载至Claude系统提示，仅提供核心信息，让Claude判断是否需要调用该Skill，无需加载全部内容
• 第二级（SKILL.md正文）：当Claude判定Skill与当前任务相关时加载，包含该Skill的完整说明和使用指导
• 第三级（链接文件）：Skill目录中的附加文件，Claude可根据任务需求选择性浏览、调用

2. 可组合性 (Composability)

Claude支持同时加载多个Skill，因此单个Skill需具备良好的协作性，不可假设自身是唯一可用的能力，需兼容与其他Skill的搭配使用。

3. 可移植性 (Portability)

Skill具备跨平台一致性，在Claude.ai、Claude Code、Claude API上表现完全相同；只需创建一次，所有平台均可直接使用（前提是平台环境支持该Skill的依赖项）。

如果已拥有可用的MCP服务器，核心开发工作已完成，Skill是基于MCP的顶层知识层，核心作用是固化已有的工作流程和**实践，让Claude能标准化、一致性地应用MCP能力。

1. 厨房比喻：直观理解MCP与Skill的关系

• MCP：提供专业厨房，即各类工具、食材、设备的访问权限
• Skill：提供食谱，即利用厨房资源创造价值的分步操作说明

二者结合，能让用户无需自行摸索步骤，即可完成复杂任务。

2. MCP与Skill的协同工作逻辑

二者是连接性与知识层的互补关系，分别解决Claude“能做什么”和“应该怎么做”的问题：

3. Skills对MCP用户的核心价值

无Skills的MCP使用痛点

• 用户连接MCP后无明确操作指引，不知下一步如何行动
• 大量支持工单集中于“如何用集成做X”的基础问题
• 每次对话均从零开始，无历史工作流程复用
• 因用户提示方式不同，任务结果一致性差
• 问题根源是缺乏工作流程指导，但用户易归咎于MCP连接器本身

有Skills的MCP使用优势

• 预构建工作流程可根据任务需求自动激活
• Claude对MCP工具的使用更一致、更可靠
• 所有交互均嵌入行业/场景**实践，提升结果质量
• 大幅降低MCP集成的学习曲线，提升用户使用体验

在编写任何代码前，需先明确Skill要支持的2-3个具体用例——这是确保Skill贴合用户实际需求、避免无的放矢的关键前提。

1. 高质量用例的定义标准

完整的用例需包含触发条件、执行步骤和可落地结果，示例如下：

用例：项目冲刺规划

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

步骤：

从 Linear 获取当前项目状态（通过 MCP）

分析团队速度和容量

建议任务优先级

在 Linear 中创建带有适当标签和估算的任务

结果：完全规划的冲刺，任务已创建

2. 定义用例时的核心自问

• 用户最终想要完成什么目标？
• 达成目标需要哪些多步骤的工作流程？
• 过程中需要用到哪些工具（Claude内置能力/第三方MCP）？
• 应该嵌入哪些领域知识或行业**实践？

3. 三类常见的Skill用例类别

Anthropic总结了实践中最高频的三类Skill用例，覆盖绝大多数场景需求：

成功标准是判断Skill是否有效运行的依据，分为定量（可量化）和定性（体验/一致性）两类，均为粗略基准而非精确阈值。

1. 定量指标（可直接测量）

• 触发率：90%的相关查询能自动触发Skill

→ 测量方式：运行10-20个目标测试查询，统计自动加载vs需用户显式调用的次数

• 执行效率：在预设的X次工具调用内完成工作流

→ 测量方式：对比有无Skill时，相同任务的工具调用次数、总token消耗量

• 稳定性：每个工作流的API调用0失败

→ 测量方式：测试期间监控MCP服务器日志，跟踪重试率、错误代码

2. 定性指标（基于体验评估）

• 自主性：用户无需提示Claude“下一步该做什么”

→ 评估方式：测试中记录需重定向/澄清的频率，收集测试用户反馈

• 准确性：工作流完成后无需用户手动纠正

→ 评估方式：对同一请求运行3-5次，对比输出的结构、质量一致性

• 易用性：跨会话输出结果一致，新用户可在最少指导下首次完成任务

→ 评估方式：验证新用户首次使用的任务完成度

1. 标准文件结构

Skill文件夹需遵循固定结构，明确区分必需文件和可选文件：

your-skill-name/

├── SKILL.md              # 必需 - 主Skill文件（核心）

├── scripts/              # 可选 - 可执行代码（Python/Bash等）

│   ├── process_data.py   # 示例：数据处理脚本

│   └── validate.sh       # 示例：验证脚本

├── references/           # 可选 - 按需加载的参考文档

│   ├── api-guide.md      # 示例：API使用指南

│   └── examples/         # 示例：用例示例目录

└── assets/               # 可选 - 模板/字体/图标等资源

    └── report-template.md # 示例：报告模板

2. 核心命名规则

（1）SKILL.md命名

• 必须严格匹配：SKILL.md（区分大小写）
• 禁止变体：SKILL.MD、skill.md、Skill.md等均不被识别

（2）Skill文件夹命名

• 强制：使用短横线命名法（kebab-case），如notion-project-setup ✅
• 禁止：空格（NotionProjectSetup❌）、下划线（notion_project_setup ❌）、大写字母（NotionProjectSetup ❌）

（3）README.md规范

• 禁止：在Skill文件夹内放置README.md
• 要求：所有文档需归入SKILL.md或references/目录
• 例外：通过GitHub分发时，仓库根目录可保留README.md（供人类用户阅读）

YAML前置元数据是Claude判断“是否加载该Skill”的依据（渐进式披露的第一级），需严格遵循格式与规则。

1. 最小必需格式

—

name: your-skill-name

description: 它的作用。当用户要求[特定短语]时使用。

---

2. 字段详细要求

（1）必需字段

（2）可选字段

3. 安全限制（禁止项）

• 前置元数据中禁止出现XML尖括号（< >）
• Skill名称中禁止包含”claude”或”anthropic”（Anthropic保留词）

→原因：前置元数据会进入Claude的系统提示，需防止恶意内容注入指令。

1. description字段：精准触发的关键

description需同时传递“功能+触发条件+核心能力”，是Claude识别Skill的核心依据。

优秀示例

• 具体可操作：

description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求”设计规范”、”组件文档”或”设计到代码交接”时使用。

• 触发短语明确：

description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到”冲刺”、”Linear任务”、”项目规划”或要求”创建工单”时使用。

• 价值主张清晰：

description: PayFlow 的端到端客户入门工作流。处理账户创建、支付设置和订阅管理。当用户说”入门新客户”、”设置订阅”或”创建 PayFlow 账户”时使用。

反面示例（需避免）

• 过于模糊：description: 帮助处理项目。
• 缺少触发条件：description: 创建复杂的多页文档系统。
• 仅技术表述，无用户触发场景：description:实现具有层级关系的 Project 实体模型。

2. 主指令编写（SKILL.md正文）

前置元数据后，需用Markdown编写Skill的实际执行指令，推荐通用模板（可按需调整）：

—

name: your-skill

description: […]

---

你的 Skill 名称

指令

步骤 1：[第一个主要步骤]

清晰说明该步骤的执行逻辑、具体操作内容。

示例：

”`bash

python scripts/fetch_data.py –project-id PROJECT_ID

预期输出：[描述成功执行后的结果形态，如“返回包含项目所有未完成任务的JSON文件”]

示例

示例 1：[常见使用场景]

用户说：”设置一个新的营销活动”

操作：

1. 通过 MCP 获取现有营销活动列表
2. 基于用户提供的参数创建新活动

结果：活动已创建，返回活动详情确认链接

故障排除

错误：[常见错误消息，如“MCP连接超时”]

原因： [错误产生的核心原因，如“MCP服务器未启动”]

解决方案： [具体修复步骤，如“1. 检查MCP服务器状态；2. 重启服务器后重试”]

 六、指令编写的**实践 1. 具体且可操作（避免模糊表述） ✅ 推荐： 运行 python scripts/validate.py  --input {filename} 检查数据格式。 如果验证失败，常见问题包括：

• 缺少必填字段（需补充到CSV文件中）
• 无效日期格式（需统一为YYYY-MM-DD）❌ 避免： 在继续之前验证数据。

  2. 内置错误处理逻辑明确列出常见问题及解决步骤，示例：

  ”`markdown 常见问题

  MCP 连接失败若看到”Connection refused”错误：

1. 验证 MCP 服务器是否运行：进入 Settings > Extensions 查看状态
2. 确认API密钥有效且未过期3. 重新连接：Settings > Extensions > [你的服务] > Reconnect

   3. 清晰引用捆绑资源

   明确指向Skill内的附加资源，减少信息冗余，示例：

   编写查询前，请查阅
   references/api-patterns.md 了解：
   
   
   
   

   • - API速率限制规则
   • - 数据分页处理模式
   • - 常见错误代码及处理方案

   4. 遵循渐进式披露原则

   SKILL.md仅保留核心执行指令，将详细文档（如完整API文档、复杂示例）移至references/目录，并通过链接引用——既保证核心逻辑清晰，又能按需加载详细信息，最小化token消耗。

   总结

   1. Skill规划需先定义2-3个具体用例，明确触发条件、执行步骤和结果，同时参考文档创建、工作流自动化、MCP增强三类高频场景；
   2. 成功标准分定量（触发率、效率、稳定性）和定性（自主性、准确性、易用性）两类，用于验证Skill效果；
   3. Skill需遵循固定文件结构和命名规则，YAML前置元数据是触发核心，description字段需同时包含功能和触发条件；
   4. 指令编写需具体可操作、内置错误处理、清晰引用资源，并遵循渐进式披露原则。

   Skill的测试可根据质量要求和使用场景（可见性）选择不同严谨度的方式，从快速手动验证到系统化程序化测试均可实现；同时迭代优化有核心技巧，能大幅提升开发效率，最终Skills需基于实际使用反馈持续更新，成为适配需求的“活文档”。

   

   适配不同使用场景的测试需求，从个人/小团队内部使用，到企业级大规模部署，可按需选择，无额外前置设置的手动测试适合快速迭代，程序化测试适合高要求的正式部署。

   1. Claude.ai手动测试：直接输入查询并观察Skill执行行为，无需额外设置，适合快速迭代验证核心逻辑
   2. Claude Code脚本化测试：将测试用例自动化，便于Skill更新变更时，进行可重复的结果验证
   3. SkillsAPI程序化测试：构建专业评估套件，针对预定义的测试集进行系统性、标准化的批量运行

   专业创作提示：先聚焦单个任务迭代，再扩展场景

   高效的Skill开发思路是：先针对一个有挑战性的核心任务反复迭代，直到Claude能稳定成功执行，再将成功方法提炼到Skill中；这种方式利用Claude的上下文内学习能力，能获得比广泛测试更快的反馈，待基础版本可用后，再扩展多测试用例覆盖更多场景。

   结合实践经验，有效的Skill测试需覆盖触发、功能、性能三大核心领域，层层验证Skill的有效性和实用性。

   1. 触发测试

   核心目标：确保Skill在正确的场景/指令下自动加载，无关场景下不触发，避免漏触发或误触发。

   核心测试用例：

   • ✅ 明显匹配Skill用途的任务指令，能正常触发
   • ✅ 同义改写的同类请求，能正常触发
   • ❌ 不相关主题的指令，不触发

   测试套件示例（以ProjectHub Skill为例）

   • 应该触发：
   • “Help me set up a new ProjectHub workspace”
   • “I need to create a project in ProjectHub”
   • “Initialize a ProjectHub project for Q4 planning”
   • 不应该触发：
   • “What’s the weather in San Francisco?”
   • “Help me write Python code”
   • “Create a spreadsheet”（除非该Skill明确支持表格处理）

   2. 功能测试

   核心目标：验证Skill能稳定执行工作流，产生符合预期的正确输出，包含异常处理和边界情况。

   核心测试用例：

   • 能生成符合要求的有效输出
   • 涉及的API/MCP调用能100%成功
   • 遇到错误时，内置的错误处理逻辑能有效生效
   • 能覆盖业务场景中的边界情况（如极值、特殊参数）

   测试示例（以创建项目任务为例）

   测试：创建带有5个任务的项目

   给定：项目名称”Q4 Planning”，5条具体的任务描述

   当：Skill完整执行预设工作流时

   那么：

   该项目在ProjectHub中成功创建

   5个任务均以正确的属性（名称、描述等）创建

   所有任务均正确关联至该项目

   全程无任何API/MCP调用错误

   3. 性能对比

   核心目标：通过量化指标，证明有Skill的执行效果远优于无Skill的基线状态，验证Skill的实际价值。

   测试依据：使用前文「定义成功标准」中的定量/定性指标，对比“有/无Skill”完成相同任务的差异。

   基线对比示例（同任务下）

   维度	无Skill（基线）	有Skill
   交互方式	用户需逐步提供指令	自动执行预设工作流
   来回消息数	15条	仅2个澄清问题
   失败的API调用数	3次（需手动重试）	0次
   token消耗量	12,000	6,000

   skill-creator是Anthropic官方的辅助Skill，可通过Claude.ai插件目录获取或下载至Claude Code使用，核心作用是降低Skill开发门槛——若已有可用的MCP服务器，且明确了2-3个核心工作流，可在15-30分钟的单次会话中，快速构建并测试出一个可实际使用的Skill。

   核心能力1：快速创建Skill

   • 根据用户的自然语言描述，自动生成Skill的核心内容
   • 生成格式完全合规、带YAML前置元数据的SKILL.md文件
   • 智能建议贴合场景的触发短语和Skill文档结构

   核心能力2：专业审查Skill

   • 自动标记Skill中的常见问题（如描述模糊、缺少触发条件、结构混乱）
   • 识别潜在的过度触发/不足触发风险，并给出优化建议
   • 根据Skill声明的用途，量身推荐针对性的测试用例

   核心能力3：辅助迭代改进

   • 当使用自研Skill遇到边界情况/执行失败时，可将问题案例反馈给skill-creator
   • 示例指令：”使用本次聊天中发现的问题和解决方案，改进这个Skill处理[某特定边界情况]的逻辑”

   基础使用方法

   直接在Claude中输入指令：

   Use the skill-creator skill to help me build a skill for [你的具体用例]

   ⚠️ 注意：skill-creator仅负责Skill的设计、编写和完善，不支持执行自动化测试套件，也无法生成定量的性能评估结果。

   若测试/使用中发现Skill执行异常，先聚焦解决核心执行问题，再进行精细化迭代，常见问题及对应解决方案如下：

   常见执行问题	核心解决方案
   执行结果不一致	优化指令描述，让步骤更具体
   API/MCP调用失败	补充完善的错误处理逻辑
   输出结果需用户手动纠正	细化输出标准，明确属性要求

   Skills并非一次性编写完成的静态文档，需根据实际使用中的用户反馈和触发信号持续优化，核心解决触发不足和触发过度两大核心问题，让Skill的触发逻辑更精准。

   场景1：触发不足（该加载时未加载）

   核心信号：

   • Skill在匹配的场景下，未自动加载
   • 用户需要手动启用Skill才能执行
   • 出现大量询问“该怎么用这个Skill”的支持问题

   解决方案：在YAML前置元数据的description字段中，补充更多细节和差异化描述，加入场景相关的技术术语、同义关键词，扩大精准触发范围。

   场景2：触发过度（无关场景下误加载）

   核心信号：

   • Skill在不相关的查询下，错误自动加载
   • 用户频繁手动禁用Skill
   • 出现大量对Skill用途的困惑性提问

   解决方案：在description字段中添加否定触发条件，让描述更具体、更聚焦核心场景，缩小触发范围，避免误匹配。

   Skill的分发与分享是让其落地实用、放大价值的关键环节，不仅能让MCP集成更完整，还能凭借“即装即用的工作流”形成差异化优势；目前Anthropic已支持个人/组织级多场景分发，同时推出开放标准保障跨平台兼容性，还提供了API级程序化使用方案，搭配标准化的托管、文档和推广方法，能大幅提升Skill的传播和使用效率。

   

   Skills是MCP集成的重要补充，能让你的MCP连接器在同类产品中更具竞争力：

   • 带有Skills的MCP，能为用户提供更快的价值实现路径，无需用户自行摸索工作流
   • 相比纯MCP替代方案，Skill+MCP的组合能实现“连接工具+落地方法”的一站式体验，大幅降低用户使用门槛

   适配个人用户和企业组织用户的不同使用需求，提供灵活的部署、更新和管理方式：

   1. 个人用户获取&使用Skill

   步骤简单易操作，支持Claude.ai和ClaudeCode双平台，全程无复杂配置：

   1. 下载Skill完整文件夹（含SKILL.md及各类可选目录）
   2. 若需要，对文件夹进行压缩处理
   3. cladueAI端：通过「Settings > Capabilities > Skills」上传
   4. cladue代码端：直接将文件夹放置在Claude Code的Skills专属目录中

   2. 组织级Skill部署（2025年12月18日正式推出）

   针对企业/团队的规模化使用需求，提供专业化的管理能力：

   • 由管理员统一操作，可在整个工作区范围内批量部署Skill
   • 支持Skill自动更新，无需团队成员手动重新下载安装
   • 提供集中化管理能力，可统一管控Skill的启用/禁用、权限分配

   Anthropic已将Agent Skills作为开放标准正式发布，核心理念与MCP一致——让Skill具备跨工具、跨平台的可移植性：

   • 核心原则：无论使用Claude还是其他AI平台，相同的Skill应能正常工作，无需重复开发
   • 灵活适配：若部分Skill为充分利用特定平台能力定制，作者可在Skill的compatibility（兼容性）字段中明确标注平台要求
   • 生态合作：Anthropic正与生态系统成员深度协作完善该标准，目前已迎来大量早期采用者

   针对构建应用、开发代理、自动化工作流等程序化用例，Claude提供了Skills API，能实现对Skill的精细化、自动化控制，满足大规模生产级使用需求。

   1. API核心能力

   • 提供/v1/skills专属端点，支持Skill的批量列出、新增、删除等管理操作
   • 可通过container.skills参数，在MessagesAPI请求中直接指定启用的Skill
   • 支持在Claude Console中对Skill进行版本控制和集中管理
   • 可与Claude Agent SDK深度配合，快速构建集成Skill能力的自定义代理

   2. API vs 端侧（Claude.ai/Claude Code）：使用场景选择

   根据实际需求选择**使用平台，让Skill的价值在对应场景中最大化：

   具体用例	**使用平台
   最终用户直接与Skill交互使用	Claude.ai / Claude Code
   Skill开发期间的手动测试、快速迭代	Claude.ai / Claude Code
   个人/小团队的临时工作流处理	Claude.ai / Claude Code
   构建集成Skill能力的程序化应用	Skills API
   Skill的大规模生产级部署	Skills API
   自动化流水线、自定义代理系统开发	Skills API

   Anthropic推荐GitHub托管+MCP文档联动+专属安装指南的标准化方案，能让用户快速找到、安装并使用你的Skill，大幅提升传播效率和用户体验。

   步骤1：在GitHub上托管Skill

   核心是让用户能便捷获取Skill，同时清晰了解使用方法：

   • 开源Skill：直接使用公共仓库托管
   • 必备文档：编写清晰的仓库级README（供人类阅读，与Skill文件夹内的内容分离，Skill文件夹内禁止放README.md）
   • 内容补充：README中需包含安装说明、使用示例、操作截图，降低用户试错成本

   步骤2：在MCP仓库中做联动记录

   将Skill与MCP深度绑定，让MCP用户主动发现Skill的价值：

   • 文档联动：在你的MCP仓库文档中，专门添加一个Skill相关章节，并直接链接到Skill的GitHub仓库
   • 价值说明：清晰解释“Skill+MCP”组合使用的核心价值，让用户理解为何需要一起使用
   • 快速入门：提供简洁的“MCP+Skill”组合使用快速指南，一步到位教用户落地

   步骤3：创建专属Skill安装指南

   为用户编写步骤化、无门槛的安装指南。

   Skill的描述方式，直接决定用户是否理解其价值、是否愿意尝试使用——无论在README、MCP文档还是营销材料中，描述Skill都需遵循重结果、轻功能，强绑定MCP 的核心原则。

   技巧1：关注结果，而非功能（用户视角）

   用户关心的是“Skill能帮我解决什么问题、节省多少成本”，而非Skill的技术实现细节：

   ✅ 优秀示例：

   “ProjectHub Skill 让团队能够在几秒钟内设置完整的项目工作空间——包括页面、数据库和模板——而不是花费 30 分钟进行手动设置。”

   ❌ 反面示例：

   “ProjectHub Skill 是一个包含 YAML 前置元数据和 Markdown 指令的文件夹，调用我们的 MCP 服务器工具。”

   技巧2：突出MCP + Skills的组合故事（绑定价值）

   清晰传递“MCP提供连接能力，Skill提供落地方法”的核心逻辑，让用户理解二者是不可分割的整体：

   示例：

   “我们的MCP服务器让Claude能够访问你的Linear项目。我们的Skills教 Claude 你团队的冲刺规划工作流。它们共同实现了AI驱动的项目管理。”

   经Anthropic早期采用者和内部团队验证的5大有效设计模式（非硬性模板，可按需适配），以及Skill使用中上传、触发、执行等高频问题的保姆级故障排除方案。先明确Skill设计的核心方法论选择，再落地5大实用模式，最后针对各类问题给出具体、可落地的解决办法，覆盖从开发到使用的全流程问题。

   

   这是Skill设计的底层框架选择，类比家得宝五金店的使用逻辑，两种思路适配不同用户需求，大多数Skill会偏向其中一个方向，选对框架才能匹配后续的设计模式。

   • 核心逻辑：用户要么带着问题找工具，要么拿着工具找解决问题的方法，Skill需对应贴合这两种用户行为
   • 问题优先：用户描述想要的结果，Skill负责编排工具/步骤

   示例：用户说“我需要设置一个项目工作空间”→Skill按顺序调用对应的MCP工具完成操作，用户无需关注工具细节

   • 工具优先：用户已有工具访问权限，Skill负责提供专业知识/**工作流

   示例：用户说“我已连接NotionMCP”→Skill教Claude如何用Notion MCP实现高效的项目管理，注入行业**实践

   5.2 5大经典Skill设计模式（实战验证有效）

   以下模式是从实际使用中提炼的通用方法，可单独使用也可组合适配复杂场景，每个模式均明确适用场景、实战示例和关键技术，直接抄作业即可。

   模式1：顺序工作流编排

   适用场景：用户需要按固定特定顺序执行多步骤流程，步骤间存在明显的依赖关系

   实战示例：新客户入职全流程

    工作流：新客户入职

步骤 1：创建账户

调用MCP工具：create_customer | 参数：name, email, company

步骤 2：设置支付

调用MCP工具：setup_payment_method | 等待：支付方式验证

步骤 3：创建订阅

调用MCP工具：create_subscription | 参数：plan_id, customer_id（来自步骤1）

步骤 4：发送欢迎邮件

调用MCP工具：send_email | 模板：welcome_email_template

关键技术：

• 明确的步骤先后排序，标注步骤间的依赖关系
• 每个步骤执行后做结果验证，确保符合要求再推进
• 步骤执行失败时，提供回滚指令，避免流程中断产生无效数据

模式2：多MCP协调

适用场景：工作流需要跨多个服务/平台完成，需协调不同MCP服务器配合工作

实战示例：设计到开发的全流程交接（Figma+Drive+Linear+Slack MCP）

 设计到开发交接

阶段1：设计导出（Figma MCP）

1. 导出设计资源 2. 生成设计规范 3. 创建资源清单

阶段2：资源存储（Drive MCP）

1. 创建项目文件夹 2. 上传所有资源 3. 生成可分享链接

阶段3：任务创建（Linear MCP）

1. 创建开发任务 2. 附加资源链接 3. 分配给工程团队

阶段4：通知同步（Slack MCP）

1. 发布交接摘要到

#engineering

 2. 附带资源链接+任务引用

关键技术：

• 按业务逻辑做清晰的阶段分离，每个阶段对应一个/一类MCP
• 实现MCP之间的数据无缝传递（如Drive链接传递给Linear）
• 进入下一阶段前做全局验证，避免单环节出错影响整体
• 搭建集中式错误处理逻辑，任一MCP调用失败均有统一的应对方案

模式3：迭代优化

适用场景：输出结果的质量需要通过多次迭代提升，需反复验证、优化直至达到标准

实战示例：自动化报告生成

 迭代报告创建

初始草稿

1. MCP获取数据 2. 生成报告初稿 3. 保存到临时文件

质量检查

1. 运行验证脚本：scripts/check_report.py
2. 识别问题：缺少部分/格式不一致/数据验证错误

优化循环

1. 解决识别的问题 2. 重新生成受影响部分 3. 重新验证 4. 重复至达标

最终确定

1. 应用最终格式 2. 生成内容摘要 3. 保存最终版本

关键技术：

• 提前定义明确的质量标准/阈值，明确“迭代到什么程度停止”
• 搭建可复用的迭代优化循环，无需手动干预重复步骤
• 配合验证脚本做程序化检查，比人工判断更精准
• 做好迭代过程的版本管理，避免覆盖有效内容

模式4：上下文感知工具选择

适用场景：实现相同的业务结果，但需要根据不同的上下文/条件选择不同的工具

实战示例：智能文件存储（根据文件属性选择存储方式）

 智能文件存储

决策树（上下文判断）

1. 检查文件类型+大小
2. 确定存储位置：

   - 大文件（>10MB）→ 云存储MCP

   - 协作文档 → Notion/Docs MCP

   - 代码文件 → GitHub MCP

   - 临时文件 → 本地存储

执行存储

1. 调用对应MCP工具 2. 添加服务专属元数据 3. 生成访问链接

上下文反馈

向用户解释选择该存储方式的原因，提升透明度

关键技术：

• 制定清晰、可量化的决策标准（如文件大小阈值、类型分类）
• 为每种选择设置回退选项，避免决策条件不匹配时流程中断
• 向用户透明化工具选择逻辑，让用户理解背后的原因
• 支持决策条件的灵活扩展，适配后续新增的存储工具

模式5：领域特定智能

适用场景：Skill需要在工具访问基础上，注入行业/领域的专业知识、规则或标准，实现更专业的自动化

实战示例：金融合规的支付处理

 合规支付处理

处理前（合规检查）

1. MCP获取交易详情 2. 应用合规规则（制裁名单/司法管辖区/风险级别）3. 记录合规决策

交易处理

• 合规通过：调用支付MCP+欺诈检查+完成交易
• 不合规：标记审查+创建合规案例

审计追踪

1. 记录所有合规检查结果 2. 记录处理决策 3. 生成标准化审计报告

关键技术：

• 将领域专业知识/规则嵌入Skill的执行逻辑中，先做专业判断再执行工具
• 遵循“先合规，后行动”的核心原则，确保操作符合行业标准
• 搭建全面的文档/审计追踪体系，记录每一步操作和决策
• 设计清晰的治理逻辑，明确不合规场景的处理流程

针对Skill使用中最常见的上传失败、触发异常、指令未执行、MCP连接失败、性能下降6类问题，逐一说明症状、原因、具体解决方案/检查清单/调试技巧，所有方法均经过实战验证，直接落地即可。

问题1：Skill无法上传

上传时直接报错，核心原因均为文件命名/格式/配置不满足规范，3个最常见错误及解决办法如下：

错误1：提示“在上传文件夹中找不到 SKILL.md”

• 原因：文件未精确区分大小写命名为SKILL.md
• 解决方案：重命名为SKILL.md（小写skill不行，大写SKILL.MD也不行）；用ls -la命令验证文件名称是否正确

错误2：提示“Invalid frontmatter”（前置元数据无效）

• 原因：YAML前置元数据的格式错误，常见为缺少分隔符、引号未闭合
• 典型错误&正确示例：

# 错误1 - 缺少—分隔符 name: my-skill description: Does things

错误2 - 引号未闭合

name: my-skill description: “Does things

✅ 正确格式

---

name: my-skill description: Does things —

错误3：提示“Invalid skill name”（Skill名称无效）

• 原因：name字段包含空格、大写字母，未遵循kebab-case命名法
• 典型错误&正确示例：

# 错误 name: My Cool Skill

✅ 正确

name: my-cool-skill

核心症状：用户发送匹配指令，Skill始终不自动加载，需手动启用

核心解决方案：优化YAML中的description字段（这是触发的核心）

快速检查清单（逐一核对）：

1. 描述是否太通用？（如“帮助处理项目”→ 无效，需具体）
2. 是否包含用户实际会说的触发短语？（如“冲刺规划”“设计交接”）
3. 若涉及文件，是否提及相关文件类型？（如.fig、.csv、.pdf）

高效调试方法：

直接问Claude：你什么时候会使用 [skill name] skill？

→Claude会直接引用你的description字段作为回答，根据缺失的信息针对性优化即可。

问题3：Skill触发太频繁（无关查询也会加载）

核心症状：Skill在不相关的用户指令下误触发，影响正常使用

3个核心解决方案（按优先级使用）：

1. 添加否定触发条件，明确排除不适用场景

示例：description:CSV文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用data-viz skill）。

2. 让描述更具体，缩小触发范围

对比：Processes documents（太宽泛）→Processes PDF legal documents for contract review（具体到文件类型+用途）

3. 明确业务范围，标注适用场景

示例：description:PayFlow支付处理，专用于电商在线支付工作流，不用于通用金融查询。

问题4：指令未被遵循（Skill加载但不按指令执行）

核心症状：Skill能正常触发，但Claude未按照SKILL.md中的指令执行，结果不符合预期

4大常见原因+对应解决方案：

1. 指令太冗长：保持指令简洁，用项目符号/编号列表排版，将详细文档移至references/目录，仅在SKILL.md保留核心步骤
2. 指令被埋没：将关键指令放在SKILL.md顶部，用Important/ Critical标注重点，核心要求可适当重复
3. 语言描述模糊：避免模糊表述，用具体、可验证的要求替代

对比：确保正确验证事物（模糊）→调用create_project前必须验证：项目名称非空、至少分配1名团队成员、开始日期不在过去（具体）

4. 模型“懒惰”：添加明确的执行鼓励，注：将该内容添加到用户提示中比SKILL.md中更有效

示例：

性能说明：花时间彻底完成操作，质量比速度更重要，禁止跳过任何验证步骤

高级技巧：

对于核心验证步骤，用脚本替代语言指令（如编写scripts/validate.py），代码执行是确定性的，比自然语言解释更精准，可参考Anthropic官方的[Office skills]示例。

问题5：MCP连接问题（Skill加载但MCP调用失败）

核心症状：Skill能正常触发，但执行到MCP调用步骤时失败，无法获取/操作第三方服务数据

4步检查清单（逐一排查，99%的问题能解决）：

1. 验证MCP服务器连接状态：Claude.ai中进入Settings> Extensions>[你的服务]，确保显示Connected（已连接）
2. 检查认证信息：确认API密钥有效未过期、已授予Skill所需的权限/范围、OAuth令牌已正常刷新
3. 独立测试MCP：让Claude不使用Skill，直接调用MCP工具（示例：使用[Service] MCP获取我的项目），若失败则是MCP本身问题，与Skill无关
4. 验证工具名称：确认SKILL.md中引用的MCP工具名称完全正确（区分大小写），可对照MCP服务器文档核对

问题6：大上下文问题（Skill运行缓慢/响应质量下降）

核心症状：Skill能正常触发和执行，但运行速度慢，或生成的结果质量下降、逻辑混乱

核心原因：

• SKILL.md内容过大，token消耗过多
• 同时启用的Skill数量太多（资源占用过高）
• 未遵循渐进式披露原则，所有内容一次性加载

3个核心解决方案：

1. 优化SKILL.md大小：将详细文档、示例移至references/目录，仅在SKILL.md中通过链接引用，保持SKILL.md5000字以下
2. 减少同时启用的Skill：避免同时启用20-50个以上Skill，按需选择性启用；可将相关能力打包成Skill“包”，减少启用数量
3. 严格遵循渐进式披露：核心指令放SKILL.md，详细信息放references/，附加资源放assets/，让Claude按需加载，而非一次性加载所有内容

这是ClaudeSkill开发的收尾核心内容，涵盖Anthropic官方全套学习资源、高效开发辅助工具、技术支持渠道，还有可直接复用的全流程快速检查清单、YAML前置元数据规范模板和生产级Skill示例，新手可直接抄作业，从开发到上线的校验、优化全流程全覆盖，确保你的Skill合规、可用、优质。

Anthropic提供了从基础指南到实战案例的全维度资源，覆盖文档、博客、示例仓库，是开发Skill的核心依据，按需求按需查阅即可。

1. 核心官方文档

• **实践指南：Best Practices Guide（Skill 开发的核心准则）
• Skills 专属文档：Skills Documentation（全流程开发细节
• API 参考文档：API Reference（程序化使用 / 部署 Skill 必备）
• MCP 文档：MCP Documentation（MCP+Skill 组合开发参考）

2. 实战博客文章

从概念介绍到场景落地，覆盖不同开发需求：

• Agent Skills 概念：Introducing Agent Skills
• 工程实战：Engineering Blog: Equipping Agents for the Real World
• Skills 核心解析：Skills Explained
• 基础开发：How to Create Skills for Claude、Building Skills for Claude Code
• 场景落地：Improving Frontend Design through Skills

3. 公开示例Skills仓库

Anthropic官方提供可直接自定义的Skill模板，无需从零开发：

• 仓库地址：GitHub [anthropics/skills]
• 包含Anthropic官方开发的各类Skill，覆盖多场景，可直接克隆、修改适配自身需求

skill-creator是Anthropic内置的Skill开发辅助工具，Claude.ai原生支持，也可用于Claude Code，能大幅降低开发门槛，实现Skill的快速生成、审查和验证，是新手必备工具。

核心能力

1. 快速生成Skill：根据自然语言描述，直接生成带YAML前置元数据的完整Skill初稿
2. 专业审查Skill：自动检查Skill的格式、逻辑问题，提供针对性优化建议
3. Skill验证评估：对已开发的Skill进行全面评估，指出待改进点

简单使用方式

直接在Claude中发送对应指令即可：

• 生成Skill：Help me build a skill using skill-creator
• 审查/优化Skill：Review this skill and suggest improvements

开发/使用Skill过程中遇到问题，可通过以下官方渠道获取支持，按问题类型选择即可：

1. 技术问题咨询：社区论坛

• 渠道：[Claude Developers Discord]
• 适用：各类Skill开发、使用的一般技术问题，可与社区开发者、Anthropic官方人员交流

2. 错误报告：GitHub Issues

• 渠道：anthropics/skills/issues
• 适用：Skill运行中的BUG、报错等问题
• 提交要求：必须包含Skill名称、完整错误信息、问题复现步骤，便于官方排查

这是Anthropic官方出品的校验清单，上传前后必看，能避免99%的基础错误；新手可先用skill-creator生成初稿，再用此清单逐一校验，确保无遗漏。

开始之前（规划阶段）

• 确定了2-3个具体的Skill用例
• 明确了所需工具（Claude内置能力/第三方MCP）
• 完整审查了官方开发指南和示例Skills
• 规划好Skill的标准文件夹结构

⚙️ 开发期间（编写阶段）

• Skill文件夹使用短横线命名法（kebab-case）
• 存在精确拼写的SKILL.md文件（区分大小写，无变体）
• YAML前置元数据包含—分隔符，格式合规
• name字段：短横线命名法，无空格、无大写字母，与文件夹名一致
• description字段：同时包含功能（WHAT）+触发条件（WHEN）
• 所有内容中无XML标签（< >），符合安全要求
• 执行指令清晰、具体、可操作
• 内置了错误处理逻辑和故障排除方案
• 提供了实际的使用示例
• 对附加资源的参考均为清晰的链接形式

上传之前（测试阶段）

• 测试过明显任务的触发效果，能正常加载
• 测试过同义改写请求的触发效果，能正常加载
• 验证过无关主题查询，不会误触发
• 所有功能测试均通过，输出符合预期
• 涉及MCP/工具集成的，能正常工作
• 已按要求压缩为.zip格式（如需）

✅ 上传之后（优化阶段）

• 在真实对话场景中测试过Skill的完整执行流程
• 持续监控Skill的触发情况，无触发不足/过度问题
• 收集了实际用户的使用反馈
• 根据反馈迭代优化了description字段和执行指令
• 在metadata中更新了Skill的版本号