Claude 技能构建完整指南官方文档

Claude 技能构建完整指南：从规划到故障排除

一、一段话总结

本文是Claude技能构建完整指南，核心讲解技能是Claude的定制化任务指令包，以SKILL.md为核心、遵循逐步披露、可组合、便携三大原则，覆盖规划设计、测试迭代、分发共享、模式排错全流程，支持独立技能与MCP增强两类开发路径，可在15-30分钟完成首个可用技能，实现工作流自动化与标准化输出。

二、思维导图

三、详细总结

1. 基础：技能核心定义与原则

技能本质

技能是文件夹形式的指令集，用于定制Claude执行重复工作流，无需反复提示。

必备结构

[SKILL.md](SKILL.md)：必填，带YAML前言的Markdown文档

可选：脚本/、引用/、assets/

三大设计原则

逐步披露：YAML元数据→正文→链接文件三级加载，节省token

可组合性：支持多技能同时加载

便携性：[Claude.ai/Code/API](Claude.ai/Code/API)跨平台兼容

技能+MCP关系

MCP：提供工具与数据连接（能做什么）

技能：提供流程与最佳实践（应该怎么做）

2. 规划与设计：从用例到规范

用例设计

先确定2-3个具体用例，明确触发条件、执行步骤、预期结果

三大用例类别

类别	用途	核心技术
类别1	文档与资产创建	风格指南、模板、质量检查
类别2	工作流自动化	分步流程、验证关口、迭代循环
类别3	MCP增强	多MCP协调、领域知识、错误处理

成功标准

定量：90%相关查询自动触发、0失败API调用

定性：无需用户引导、结果一致、新用户可上手

强制技术要求

文件名：严格[SKILL.md](SKILL.md)（区分大小写）

命名：kebab-case，无空格/大写

描述：≤1024字符，包含“功能+触发词”

禁止：XML尖括号、含claude/anthropic的名称

3. 测试与迭代：验证与优化

三种测试方式

手动测试：Claude.ai直接验证

脚本化测试：Claude Code自动化用例

API程序化测试：大规模评估

核心测试维度

触发测试：正确触发、不无关触发

功能测试：输出正确、API成功、异常处理

性能对比：减少交互次数、降低token消耗

迭代优化

触发不足：补充关键词与细节

过度触发：增加负面触发、缩小范围

执行问题：优化指令、强化错误处理

效率数据

使用技能创造者技能，15-30分钟完成首个可用技能

4. 分发与共享：部署与推广

部署方式

个人：下载→压缩→设置→功能→技能上传

组织：管理员全区部署、自动更新、集中管理

API能力

端点：/v1/skills（管理技能）

调用：container.skills参数接入Messages API

最佳分发路径

GitHub托管技能仓库，配清晰README

MCP文档中添加技能章节与链接

提供分步安装指南

5. 模式与故障排除

五大通用模式

顺序工作流编排：固定步骤执行

多MCP协调：跨服务流程联动

迭代精炼：质量检查→优化→循环

上下文感知工具选择：按场景选工具

领域特定智能：嵌入专业规则（合规/风控）

高频故障与修复

故障现象	原因	解决方案
上传失败：未找到[SKILL.md](SKILL.md)	文件名错误	改为[SKILL.md](SKILL.md)
不自动触发	描述模糊、缺触发词	补充用户常用短语
过度触发	范围太宽	加负面触发、缩小场景
MCP调用失败	连接/权限/工具名错误	检查服务器、认证、工具名
不遵循指令	说明冗长/模糊	精简、列表化、置顶关键要求