解锁AI的“职业技能树“：Claude Skills深度技术解析——从原理到实战的完全指南
当AI学会"装载技能包"，LLM应用开发的范式革命已经到来
引言：一个让AI"升级打怪"的系统
想象一下，如果你能给Claude装上"技能芯片"，让它瞬间掌握特定领域的专业知识和工作流程，会是什么样的体验？这不是科幻小说，而是Anthropic刚刚开源的Agent Skills项目带来的现实。
作为一名技术从业者，当我第一次看到这个项目时，脑海中浮现的场景是：传统的提示词工程就像教AI"临时抱佛脚"，而Skills系统则是给AI建立了一套"职业技能树"——可以随时装载、系统化、可复用的专业能力模块。这种范式转变的意义，不亚于软件工程从面向过程到面向对象的飞跃。
在本文中，我们将深入剖析Claude Skills的技术架构、设计哲学、实战应用，以及它与MCP（Model Context Protocol）的本质差异。无论你是AI应用开发者、产品经理，还是对AI技术感兴趣的技术爱好者，这篇文章都将为你打开一扇通往"AI能力工程化"的大门。
第一章：技术本质——Skills到底是什么？
1.1 从"临时工"到"专家"：Skills的核心理念
在传统的LLM交互模式中，我们通过提示词（Prompt）告诉AI该做什么。这就像每次都要给一个临时工详细讲解工作流程——效率低、容易出错、难以复用。而Skills系统的出现，彻底改变了这个游戏规则。
Skills的定义： 它是一个包含指令、脚本和资源的文件夹结构，AI可以动态加载这些内容来提升特定任务的执行能力。用技术术语来说，Skills是Agent的可插拔知识与流程模块。
让我打个更通俗的比方：
-
传统Prompt = 临时口头指导："帮我做一个PPT，要简洁大方..."
-
Skills系统 = 专业培训手册："按照《企业级PPT制作技能包》操作，包含模板、字体、配色方案和分步流程..."
1.2 技术架构：优雅的三层设计
Skills采用了一个精妙的"渐进式加载"（Progressive Disclosure）架构，这是它高效运作的关键：
┌─────────────────────────────────────────────────┐
│ Level 1: 元数据层 (Metadata) │
│ • name + description (~100 words) │
│ • 始终加载到上下文 │
│ • 决定何时触发技能 │
└─────────────────────────────────────────────────┘↓ (触发时加载)
┌─────────────────────────────────────────────────┐
│ Level 2: 核心指令层 (SKILL.md) │
│ • 详细工作流程和指南 (<5k words) │
│ • 仅在技能激活时加载 │
└─────────────────────────────────────────────────┘↓ (按需加载)
┌─────────────────────────────────────────────────┐
│ Level 3: 资源层 (Bundled Resources) │
│ • scripts/ - 可执行脚本 │
│ • references/ - 参考文档 │
│ • assets/ - 模板和资源文件 │
│ • 无限制大小（脚本可不加载直接执行） │
└─────────────────────────────────────────────────┘
这种设计有三个天才之处：
-
上下文高效性： 只在需要时加载详细内容，避免上下文窗口污染
-
模块化： 每个技能独立封装，互不干扰
-
扩展性： scripts可以直接执行而无需加载到上下文，突破token限制
1.3 文件结构剖析：一个Skill的解剖学
让我们通过一个真实案例来理解Skill的文件结构。以docx技能为例：
docx/
├── SKILL.md # 核心入口文件（必需）
│ ├── YAML前置元数据
│ │ ├── name: docx
│ │ ├── description: "文档创建、编辑和分析..."
│ │ └── license: "..."
│ └── Markdown指令内容
│ ├── 工作流决策树
│ ├── 分步骤操作指南
│ └── 最佳实践
├── scripts/ # 可执行脚本
│ ├── unpack.py # 解压docx文件
│ ├── pack.py # 打包docx文件
│ └── ...
├── references/ # 参考文档
│ ├── ooxml.md # OOXML规范详解
│ ├── docx-js.md # docx-js库文档
│ └── ...
└── ooxml/ # 相关资源└── [XSD schemas]
关键技术细节：
YAML前置元数据（必需）
---
name: docx # 技能唯一标识符（小写，连字符分隔）
description: "综合文档创建、编辑和分析工具，支持追踪更改、
评论、格式保留和文本提取。当需要处理专业文档（.docx文件）时使用"
license: "Proprietary. LICENSE.txt has complete terms"
allowed-tools: [] # 预批准的工具列表（可选）
---
-
name：必须与文件夹名称完全匹配 -
description：至关重要！这决定了Claude何时激活该技能，务必详细描述适用场景 -
allowed-tools：在Claude Code中可以预批准工具运行，减少交互确认
Markdown指令内容：工作流的精确编码
以docx技能为例，它的指令组织极为精妙：
## 工作流决策树### 读取/分析内容
使用"文本提取"或"原始XML访问"部分### 创建新文档
使用"创建新Word文档"工作流### 编辑现有文档
- **自己的文档 + 简单更改**使用"基础OOXML编辑"工作流- **他人的文档**使用**"红线标记工作流"**（推荐默认）- **法律、学术、商业或政府文档**使用**"红线标记工作流"**（必需）
这种决策树式的组织方式，让AI能够根据不同场景自动选择最合适的工作流，而不是盲目执行。
1.4 渐进式披露：上下文效率的艺术
Skills的三层加载机制背后，隐藏着深刻的工程哲学——认知负载管理。
想象一下传统方式：你给AI一个超长提示词，包含所有可能需要的信息。结果：
-
大量无关信息占用上下文窗口
-
真正重要的信息被淹没
-
token成本飙升
-
推理速度下降
Skills的渐进式披露解决方案：
| 阶段 | 加载内容 | 大小 | 触发条件 |
|---|---|---|---|
| 待命 | name + description | ~100词 | 始终加载 |
| 激活 | SKILL.md全文 | <5k词 | 用户请求匹配 |
| 执行 | 特定reference/script | 无限制 | AI主动判断需要 |
这种设计让AI能够像人类专家一样工作：
-
知道自己会什么（元数据）
-
需要时调出详细知识（SKILL.md）
-
执行时查阅具体资料（references）或使用工具（scripts）
第二章：资源分类——Scripts、References与Assets的黄金三角
一个优秀的Skill，其强大之处往往不在SKILL.md本身，而在于精心组织的bundled resources。让我们深入剖析这三类资源的设计哲学和实战技巧。
2.1 Scripts：确定性执行的守护者
设计初衷： 有些任务需要确定性和可复现性，每次都让AI重新生成代码既不可靠又浪费token。Scripts就是为此而生。
典型应用场景
场景1：PDF旋转（docx技能中的示例）
# scripts/rotate_pdf.py
import PyPDF2
import sysdef rotate_pdf(input_path, output_path, rotation):"""确定性地旋转PDF，无需AI每次重写逻辑"""with open(input_path, 'rb') as file:reader = PyPDF2.PdfReader(file)writer = PyPDF2.PdfWriter()for page in reader.pages:page.rotate(rotation)writer.add_page(page)with open(output_path, 'wb') as output_file:writer.write(output_file)if __name__ == "__main__":rotate_pdf(sys.argv[1], sys.argv[2], int(sys.argv[3]))
为什么用Script而不是让AI生成？
-
确定性： 每次执行结果完全一致
-
效率： 无需消耗token重新生成代码
-
可靠性： 经过测试的代码，不会出现AI生成的随机错误
-
版本控制： 可以像普通代码一样管理和迭代
Scripts的最佳实践
-
单一职责原则 每个script只做一件事，但做到极致。如
mcp-builder中的初始化脚本：scripts/init_skill.py <skill-name> --path <output-directory>只负责创建标准Skill目录结构，不掺杂其他逻辑。
-
完善的命令行接口
# 良好的CLI设计示例 parser = argparse.ArgumentParser(description='Rotate PDF pages') parser.add_argument('input', help='Input PDF file') parser.add_argument('output', help='Output PDF file') parser.add_argument('--rotation', type=int, choices=[90, 180, 270],default=90, help='Rotation angle') -
优雅的错误处理
try:rotate_pdf(args.input, args.output, args.rotation) except FileNotFoundError:print(f"错误：找不到文件 {args.input}", file=sys.stderr)sys.exit(1) except Exception as e:print(f"处理失败：{str(e)}", file=sys.stderr)sys.exit(1)
2.2 References：按需加载的知识库
References是技能系统中最容易被低估的部分，但它承载着核心的领域知识。
设计哲学：SKILL.md应该"瘦"
错误做法： 把所有细节都塞进SKILL.md
<!-- 这会导致SKILL.md膨胀到数万字 -->
## OOXML完整规范
（10000行的XML Schema详解...）
正确做法： SKILL.md只包含核心流程，细节放入references
<!-- SKILL.md保持精简 -->
## 编辑文档的详细语法需要时，阅读 `references/ooxml.md` 获取完整的Document Library API
和XML模式详解（约600行）。
References的实战案例分析
案例1：MCP服务器开发指南
mcp-builder/reference/目录结构：
reference/
├── mcp_best_practices.md # 通用最佳实践
├── python_mcp_server.md # Python特定指南
├── node_mcp_server.md # Node/TS特定指南
└── evaluation.md # 评估测试指南
技能指令中的精妙引用：
#### 1.4 研究框架文档（Phase 1）**加载以下参考文件：**
- [📋 MCP最佳实践](./reference/mcp_best_practices.md)**对于Python实现，同时加载：**
- [🐍 Python实现指南](./reference/python_mcp_server.md)**对于Node/TypeScript实现，同时加载：**
- [⚡ TypeScript实现指南](./reference/node_mcp_server.md)
这种设计的天才之处：
-
AI只在需要时加载特定语言的指南
-
避免无关语言的指南污染上下文
-
支持多种技术栈而不增加SKILL.md复杂度
案例2：内部沟通模板（internal-comms技能）
internal-comms/
└── examples/├── 3p-updates.md # 进度/计划/问题更新├── company-newsletter.md # 公司新闻稿├── faq-answers.md # 常见问题回答└── general-comms.md # 通用沟通指南
SKILL.md中的智能分发逻辑：
## 如何使用本技能1. **识别沟通类型**
2. **加载对应指南文件**：- 团队更新 → `examples/3p-updates.md`- 公司新闻 → `examples/company-newsletter.md`- FAQ → `examples/faq-answers.md`- 其他 → `examples/general-comms.md`
3. **遵循该文件中的格式和语气指南**
2.3 Assets：输出材料的弹药库
Assets与Scripts、References最大的区别：它们不会被加载到上下文，而是直接用于输出生成。
Assets的典型用途
1. 模板文件（artifacts-builder）
artifacts-builder/
└── scripts/└── shadcn-components.tar.gz # 预打包的React组件
当用户请求创建复杂artifact时，AI可以：
tar -xzf scripts/shadcn-components.tar.gz
# 解压40+个shadcn/ui组件，直接使用而无需重新生成
2. 字体资源（canvas-design）
canvas-design/
└── canvas-fonts/├── GeistMono-Regular.ttf├── IBMPlexSerif-Bold.ttf├── CrimsonPro-Italic.ttf└── ... (共70+字体文件)
设计海报时，AI可以直接引用这些专业字体，而不是局限于系统默认字体。
3. 样板代码（webapp-testing）
# examples/element_discovery.py
from playwright.sync_api import sync_playwright# 这是一个完整的可执行示例
# AI可以复制并修改，而不是从零开始写
with sync_playwright() as p:browser = p.chromium.launch(headless=True)page = browser.new_page()# ... 完整的测试逻辑
Assets管理的黄金准则
-
命名规范： 清晰表达用途
-
✅
react-dashboard-template/ -
❌
template1/
-
-
版本控制： 对于可能更新的assets
assets/ ├── logo-v2.png # 明确版本 ├── logo-current.png # 软链接指向当前版本 -
文档化： 在SKILL.md中说明使用方法
## 字体使用指南`canvas-fonts/`目录包含70+款专业字体。选择时考虑： - Serif字体：正式、传统感（CrimsonPro, LibreBaskerville） - Sans-serif：现代、简洁（GeistMono, Outfit） - Mono：技术感（JetBrainsMono, IBMPlexMono）
第三章：核心技能深度剖析——从Document到MCP Builder
让我们通过几个标志性的技能实现，来理解Skills系统如何处理复杂的现实场景。
3.1 Document Skills：处理二进制文件的艺术
Document skills（docx、pdf、pptx、xlsx）是整个项目中最复杂、最精妙的部分，因为它们要解决AI的一个根本性限制——处理二进制文件格式。
技术挑战：OOXML的复杂性
现代Office文档（.docx/.pptx/.xlsx）本质上是ZIP压缩的XML文件集合：
document.docx (ZIP压缩包)
├── [Content_Types].xml # 内容类型定义
├── _rels/ # 关系映射
│ └── .rels
├── word/
│ ├── document.xml # 主文档内容
│ ├── styles.xml # 样式定义
│ ├── comments.xml # 评论
│ ├── _rels/
│ │ └── document.xml.rels
│ └── media/ # 嵌入的图片等
│ ├── image1.png
│ └── ...
└── docProps/ # 文档属性├── core.xml└── app.xml
直接让AI操作这些文件有三个问题：
-
格式理解成本高： XML Schema复杂，结构嵌套深
-
容易破坏完整性： 一个标签错误可能导致文件损坏
-
token消耗巨大： 完整的OOXML规范有数千页
解决方案：分层抽象 + 脚本助手
Layer 1: 高层操作（对用户）
用户请求："帮我修改这份合同，把'30天'改成'60天'"
↓
触发docx技能
↓
AI选择：编辑现有文档 → 红线标记工作流
Layer 2: 工作流决策（SKILL.md）
## 红线标记工作流1. **获取markdown表示**```bashpandoc --track-changes=all contract.docx -o current.md
-
识别并分组更改 使用Section/heading编号定位（不是行号！）
-
读取文档 [🔗必读ooxml.md]
python ooxml/scripts/unpack.py contract.docx ./unpacked -
实现更改 a. 用grep在word/document.xml中定位文本 b. 创建Python脚本，使用Document库实现修改 c. 运行脚本
-
打包文档
python ooxml/scripts/pack.py ./unpacked reviewed-contract.docx
**Layer 3: 技术实现（references + scripts）**`references/ooxml.md` 提供了Document库的详细API：
```python
from ooxml.document import Document# 加载文档
doc = Document('unpacked/word/document.xml')# 使用高级方法查找并修改
for node in doc.find_nodes_with_text("30天"):doc.tracked_replace(node,old_text="30",new_text="60",author="Claude",rsid="00AB12CD" # 从unpack.py输出获得)# 保存修改
doc.save()
scripts/unpack.py 和 scripts/pack.py 处理ZIP操作：
# unpack.py核心逻辑
def unpack_docx(docx_path, output_dir):"""解压docx并提供有用的元数据"""with zipfile.ZipFile(docx_path, 'r') as zip_ref:zip_ref.extractall(output_dir)# 分析现有RSID，建议新的suggested_rsid = generate_unique_rsid(output_dir)print(f"建议使用RSID: {suggested_rsid}")print("在tracked_replace中使用此RSID以标记你的更改")
深度洞察：为什么是这样的分层设计？
这个设计体现了关注点分离（Separation of Concerns）的极致：
| 层级 | 关注内容 | 谁使用 |
|---|---|---|
| 用户层 | "我要改合同" | 终端用户 |
| 流程层（SKILL.md） | 工作流步骤、何时用什么工具 | AI决策引擎 |
| 技术层（references） | Document库API、XML结构 | AI实现引擎 |
| 执行层（scripts） | 确定性操作（ZIP解压） | 直接执行 |
为什么不能简化？
-
去掉scripts → AI每次重写ZIP操作，容易出错
-
去掉references → SKILL.md膨胀到数万字，上下文爆炸
-
去掉工作流决策树 → AI不知道何时用红线标记vs直接编辑
3.2 MCP Builder：元技能的奇妙实现
mcp-builder是整个项目中最"元"的技能——它是一个教AI如何创建其他集成系统的技能。
技术背景：MCP是什么？
MCP（Model Context Protocol）是一个让LLM连接外部服务的协议。通俗理解：
传统方式：
用户 → AI → "我不能访问你的Notion数据库"MCP方式：
用户 → AI → MCP Server (Notion) → Notion API↓返回数据给AI进行处理
MCP Server就像给AI装了一个"API转接器"，让它能调用外部服务。
mcp-builder的任务：教AI写高质量的MCP Server
挑战： 写MCP Server需要懂：
-
MCP协议规范
-
RESTful API设计
-
错误处理和验证
-
异步编程
-
安全认证
-
...这些加起来可能是数万字的知识
mcp-builder的解决方案：四阶段方法论
## 高层工作流### Phase 1: 深入研究与规划
1.1 理解Agent-Centric设计原则"不要简单包装API端点——构建工作流工具"1.3 学习MCP协议文档使用WebFetch加载：https://modelcontextprotocol.io/llms-full.txt1.4 学习框架文档Python → 加载python_mcp_server.mdNode → 加载node_mcp_server.md1.5 穷尽研究API文档目标服务的所有端点、认证、限速...1.6 创建实现计划- 工具选择（哪些端点最有价值）- 共享工具设计- 输入/输出设计- 错误处理策略### Phase 2: 实现
2.1 设置项目结构
2.2 实现核心基础设施（API助手、错误处理）
2.3 系统化实现工具
2.4 遵循语言特定最佳实践### Phase 3: 审查与精炼
3.1 代码质量审查（DRY、类型安全...）
3.2 测试与构建
3.3 使用质量检查清单### Phase 4: 创建评估
4.1 理解评估目的
4.2 创建10个评估问题
4.3 验证答案
这个流程的天才之处：
-
先研究后实现
❌ 错误：立即开始写代码 ✅ 正确：Phase 1花大量时间研究API、阅读文档、规划设计 -
按需加载专业知识
如果是Python实现： - 加载 python_mcp_server.md（Python特定模式） - 忽略 node_mcp_server.md（避免混淆）如果是TypeScript实现： - 加载 node_mcp_server.md - 忽略 python_mcp_server.md -
内置质量保证
### Quality Checklist（来自references）#### 工具设计 - [ ] 所有工具名称包含服务前缀（slack_send_message） - [ ] 支持JSON和Markdown响应格式 - [ ] 实现分页（limit, offset, has_more） - [ ] 字符限制和截断（CHARACTER_LIMIT = 25000）#### 错误处理 - [ ] 所有API调用有try/except - [ ] 错误消息是LLM友好的自然语言 - [ ] 建议下一步操作#### 类型安全 - [ ] Python: 完整类型提示 + Pydantic v2 - [ ] TypeScript: strict mode, 无any类型
实战示例：创建Slack MCP Server的流程
让我们模拟AI使用mcp-builder技能的完整过程：
Step 1: 触发技能
用户："帮我创建一个Slack MCP Server"
↓
Claude加载mcp-builder技能
Step 2: Phase 1 - 研究
AI内心独白：
"我需要先理解要做什么..."1. 加载 reference/mcp_best_practices.md学到：工具命名规范、响应格式、分页模式...2. 使用WebFetch加载MCP协议文档学到：MCP的JSON-RPC结构、工具注册方法...3. 选择Python → 加载 reference/python_mcp_server.md学到：FastMCP框架使用、Pydantic模型定义...4. 网络搜索"Slack API documentation"学到：可用的API端点- conversations.list （获取频道列表）- chat.postMessage （发送消息）- users.list （获取用户）- ...5. 创建实现计划：核心工具：- slack_list_channels (limit, types, exclude_archived)- slack_send_message (channel, text, thread_ts?)- slack_search_messages (query, sort, count)共享工具：- format_response(data, format='markdown')- paginate_results(items, limit, offset)- handle_api_error(error)
Step 3: Phase 2 - 实现
# AI生成的代码框架
from mcp import FastMCP
from pydantic import BaseModel, Field
import httpxmcp = FastMCP("slack_mcp")
CHARACTER_LIMIT = 25000# 共享工具
async def call_slack_api(endpoint: str, params: dict):"""统一的Slack API调用"""# ... 实现 ...def format_channels_markdown(channels: list) -> str:"""格式化频道列表为Markdown"""# ... 实现 ...# 工具定义
class ListChannelsInput(BaseModel):limit: int = Field(default=20, ge=1, le=200,description="返回的频道数量")types: str = Field(default="public_channel",description="频道类型: public_channel, private_channel")response_format: str = Field(default="markdown",description="响应格式: json或markdown")@mcp.tool(annotations={"readOnlyHint": True,"openWorldHint": True}
)
async def slack_list_channels(input: ListChannelsInput) -> str:"""列出工作区中的Slack频道。返回频道名称、ID、成员数等信息。使用limit参数控制结果数量。对于大型工作区，建议使用小的limit值（20-50）以避免超时。"""# ... 实现 ...
Step 4: Phase 3 - 审查
AI自我检查：
✅ 工具命名：slack_list_channels（包含服务前缀）
✅ 响应格式：支持JSON和Markdown
✅ 分页：实现了limit和offset
✅ 字符限制：检查响应长度，截断时提示
✅ 错误处理：所有API调用有try/except
✅ 类型安全：完整的类型提示 + Pydantic模型
✅ 文档：详细的docstring和参数说明
Step 5: Phase 4 - 评估
<!-- AI生成评估文件 -->
<evaluation><qa_pair><question>在我们的工作区中，有多少个公开频道的名称包含"engineering"？（需要：调用slack_list_channels，搜索名称，计数）</question><answer>7</answer></qa_pair><qa_pair><question>#general频道中最近10条消息的发送者中，哪个用户发送的最多？（需要：获取频道ID → 搜索消息 → 统计用户 → 找出最多的）</question><answer>U01ABC23DEF</answer></qa_pair><!-- ... 8 more complex questions ... -->
</evaluation>
3.3 Creative Skills：AI艺术创作的系统化
创意类技能（canvas-design、slack-gif-creator、algorithmic-art）展示了Skills系统的另一面——**如何系统化"创造力"**。
canvas-design：设计哲学的具象化
这个技能的独特之处在于它的两阶段创作流程：
阶段1：设计哲学创建
用户："给我设计一张关于量子计算的海报"↓ AI创建设计哲学输出：design_philosophy.md
---
# "量子几何" (Quantum Geometry)【哲学描述4-6段落】
这一运动将量子力学的不确定性原理转译为视觉语言。
通过重叠的半透明几何形状表达量子叠加态...
色彩选择遵循光谱衍射的渐变逻辑...
排版极简，文字如同观察者效应般谨慎出现...
每个元素的放置都经过无数次迭代，体现顶尖工艺...
阶段2：哲学的视觉表达
# AI根据哲学生成代码
from PIL import Image, ImageDraw, ImageFont
import numpy as np# 读取哲学中的关键元素
# - "重叠的半透明几何形状" → 使用alpha通道
# - "光谱衍射渐变" → HSV色彩空间
# - "排版极简" → 小号无衬线字体，大量留白canvas = Image.new('RGB', (2400, 3200), color=(245, 245, 250))
draw = ImageDraw.Draw(canvas, 'RGBA')# 生成量子态表示的几何图形
for i in range(15):# 重叠圆形，模拟波函数x = np.random.randint(400, 2000)y = np.random.randint(600, 2600)r = np.random.randint(200, 600)# 光谱色彩hue = (i / 15) * 360color = hsv_to_rgb(hue, 0.6, 0.8)# 半透明draw.ellipse([x-r, y-r, x+r, y+r],fill=(*color, 80)) # alpha=80# 极简排版
font = ImageFont.truetype('canvas-fonts/GeistMono-Regular.ttf', 48)
draw.text((1200, 2900), "QUANTUM", font=font,fill=(40, 40, 50), anchor='mm')canvas.save('quantum_poster.png')
为什么要分两阶段？
这是一个深刻的设计决策：
| 一步生成 | 两阶段生成 |
|---|---|
| 容易产生"AI味"的作品 | 强制AI进行深度思考 |
| 随机性高，不可复现 | 哲学可复用，变体可生成 |
| 难以迭代修改 | 可以只改哲学重新生成 |
| 缺乏内在一致性 | 所有元素都源于统一哲学 |
用技术术语说，这是抽象和实现的分离——哲学是抽象层，代码是实现层。
slack-gif-creator：组合式动画系统
这个技能展示了如何用可组合的原语（Composable Primitives）构建复杂系统。
设计模式：动画原语库
# templates/提供的原语
from templates.shake import create_shake_animation
from templates.bounce import create_bounce_animation
from templates.spin import create_spin_animation
from templates.pulse import create_pulse_animation
from templates.move import create_move_animation
# ... 还有zoom, fade, explode, wiggle, slide, flip, morph# 每个原语都是独立的、可组合的
实战：创建"惊吓"GIF
# 用户："做一个emoji被车吓到的GIF"# AI的组合策略
builder = GIFBuilder(480, 480, fps=20)# 阶段1：车接近（使用move原语）
for i in range(20):frame = create_blank_frame()t = i / 19# 车从左侧移动car_x = interpolate(50, 300, t, easing='ease_in')draw_emoji(frame, '🚗', (car_x, 300), size=60)# emoji静止draw_emoji(frame, '😰', (350, 200), size=70)builder.add_frame(frame)# 阶段2：惊吓反应（使用shake原语）
shake_frames = create_shake_animation(object_data={'emoji': '😰', 'size': 70},num_frames=15,shake_intensity=15,direction='both'
)for frame in shake_frames:# 车已经到达draw_emoji(frame, '🚗', (300, 300), size=60)builder.add_frame(frame)# 优化并保存
builder.save('scared.gif', num_colors=128)# 验证Slack限制
from core.validators import check_slack_size
passes, info = check_slack_size('scared.gif', is_emoji=False)
if not passes:print(f"文件过大（{info['size_mb']:.2f}MB），需要优化")
组合的力量：
相比于写一个"惊吓动画"脚本，原语系统的优势：
-
可复用性： shake原语可用于地震、愤怒、兴奋等任何需要震动的场景
-
可测试性： 每个原语独立测试，组合时更可靠
- 创造力： AI可以自由组合，创造无限变体
# 例如：弹跳 + 旋转 + 爆炸 bounce_frames = create_bounce_animation(...) spin_frames = create_spin_animation(...) explode_frames = create_explode_animation(...) # 拼接成复杂动画序列
第四章：Skills vs MCP——两种范式的本质差异
现在我们已经深入理解了Skills，是时候解答一个关键问题：Skills和MCP有什么区别？为什么需要两个系统？
4.1 定位差异：知识 vs 能力
用一个类比来理解：
| Skills | MCP | |
|---|---|---|
| 类比 | 专业培训手册 | 工具箱 |
| 核心价值 | 传授"怎么做"的知识 | 提供"做什么"的能力 |
| 本质 | 程序性知识（Procedural Knowledge） | 工具接口（Tool Interface） |
Skills的典型场景：
用户："帮我审查这份法律合同，使用红线标记修改"Skills提供：
- 法律文档审查的最佳实践
- 红线标记的标准流程
- OOXML编辑的技术知识
- 分步骤的决策树结果：AI知道如何专业地审查合同
MCP的典型场景：
用户："查看我Notion数据库中所有待办事项"MCP提供：
- notion_get_databases() 工具
- notion_query_database() 工具
- notion_get_page() 工具结果：AI能够调用Notion API获取数据
4.2 技术架构差异
Skills架构：静态资源 + 动态加载
┌─────────────────────────────────┐
│ Claude AI │
│ ┌───────────────────────┐ │
│ │ 加载的Skills │ │
│ │ - SKILL.md指令 │ │
│ │ - References文档 │ │
│ │ - Scripts可执行 │ │
│ └───────────────────────┘ │
│ ↓ │
│ 【推理 + 执行脚本】 │
└─────────────────────────────────┘
MCP架构：客户端-服务器模式
┌──────────────┐ JSON-RPC ┌──────────────┐
│ Claude AI │ ←─────────────────→ │ MCP Server │
│ (Client) │ tools/list │ (Notion) │
│ │ tools/call │ │
└──────────────┘ └──────────────┘↓┌──────────────┐│ Notion API │└──────────────┘
4.3 交互模式差异
Skills：上下文内推理
# Skills方式：AI在自己的上下文中执行
def review_contract(contract_path):# 1. AI读取SKILL.md，学习流程workflow = load_skill("docx")# 2. AI执行脚本（仍在自己的环境中）run_script("ooxml/scripts/unpack.py", contract_path)# 3. AI生成Python代码修改XMLgenerate_and_run_modification_script()# 4. AI执行打包脚本run_script("ooxml/scripts/pack.py", output_path)
MCP：工具调用
# MCP方式：AI通过协议调用外部服务
async def get_notion_tasks():# 1. AI发现可用工具tools = await mcp_client.list_tools()# → [notion_query_database, notion_get_page, ...]# 2. AI决定调用哪个工具result = await mcp_client.call_tool("notion_query_database",{"database_id": "abc123","filter": {"property": "Status", "equals": "Todo"}})# 3. MCP Server执行真实API调用# → Notion API# → 返回结果给AI
4.4 使用场景对比
| 场景维度 | Skills更适合 | MCP更适合 |
|---|---|---|
| 知识密集 | ✅ 复杂工作流、领域知识 | ❌ 简单API调用 |
| 需要外部服务 | ❌ 只能调用本地脚本 | ✅ 连接任何外部API |
| 需要秘密/Token | ⚠️ 可以但不安全 | ✅ Server端安全存储 |
| 实时数据 | ❌ 无法访问实时数据 | ✅ 每次调用获取最新数据 |
| 离线使用 | ✅ 完全离线可用 | ❌ 需要网络连接 |
| 自定义工作流 | ✅ 完全灵活 | ⚠️ 受限于Server提供的工具 |
4.5 协同使用：1+1>2
最强大的场景：Skills + MCP结合
想象一个"智能项目管理助手"：
## Skill: project-manager### 工作流
当用户要求"创建sprint计划"：1. 使用MCP连接Jira- 调用jira_get_issues获取backlog- 调用jira_get_sprint_info获取当前sprint2. 应用项目管理知识（Skill）- 评估任务优先级（RICE评分法）- 计算团队速度- 平衡工作负载3. 使用MCP创建计划- 调用jira_create_sprint创建新sprint- 调用jira_move_issue_to_sprint分配任务- 调用slack_send_message通知团队4. 生成文档（Skill）- 创建sprint规划文档（使用docx skill）- 生成任务甘特图（使用canvas-design skill）
这个场景中：
-
MCP 提供与Jira/Slack交互的能力
-
project-manager Skill 提供项目管理的专业知识
-
docx/canvas-design Skills 提供文档生成能力
4.6 深度洞察：为什么不能互相替代？
错误观点1："MCP可以替代Skills"
❌ 用MCP实现文档编辑：
- 需要为每个编辑操作创建一个工具→ docx_insert_text→ docx_delete_text→ docx_change_font→ ... (可能有数百个细粒度工具)
- 工作流知识无法编码（何时用红线标记？如何决策？）
- 每次调用都有网络开销✅ 用Skills实现文档编辑：
- 一个SKILL.md编码完整工作流
- 灵活的决策树（根据文档类型选择方法）
- 本地执行，无网络开销
错误观点2："Skills可以替代MCP"
❌ 用Skills连接Slack：
- Scripts无法安全存储API token
- 无法处理实时数据（Skills是静态的）
- 每个用户需要自己配置认证✅ 用MCP连接Slack：
- Server统一管理认证
- 实时API调用
- 支持OAuth等复杂认证流程
本质差异：
-
Skills = 内化的知识（像人类学习一项技能）
-
MCP = 外部的工具（像人类使用锤子、扳手）
就像一个木匠：
-
技能（Skills）：如何设计家具、如何打磨、如何拼接
-
工具（MCP）：电锯、钻头、砂纸
两者缺一不可！
解锁AI的"职业技能树"：Claude Skills深度技术解析（下篇）
接上篇
第五章：实战指南——从零创建一个Professional Skill
理论讲完了,现在让我们撸起袖子干活!我将带你完整地创建一个真实可用的Skill,体验整个开发流程。
5.1 案例需求:API Documentation Generator
场景: 你的团队需要频繁地为RESTful API生成标准化文档。每次都要：
-
分析API端点结构
-
生成OpenAPI/Swagger规范
-
创建Markdown文档
-
添加代码示例
-
生成Postman Collection
目标: 创建一个api-doc-generator技能，让Claude能够系统化地完成这些任务。
5.2 Phase 1: 需求分析与设计
5.2.1 识别核心能力
通过与"用户"（我们）的对话明确需求：
Q: "这个技能需要支持什么功能?"
A: "分析代码生成API文档，支持多种输出格式"Q: "有哪些具体的使用场景?"
A:
- "扫描Flask/FastAPI项目，自动生成OpenAPI spec"
- "根据现有API响应样本，生成文档"
- "创建交互式API文档（Swagger UI）"
5.2.2 规划Skill结构
根据分析，设计文件结构：
api-doc-generator/
├── SKILL.md # 核心工作流
├── scripts/
│ ├── init_doc_project.py # 初始化文档项目
│ ├── parse_flask_routes.py # 解析Flask路由
│ ├── parse_fastapi_routes.py # 解析FastAPI路由
│ ├── generate_openapi.py # 生成OpenAPI规范
│ └── validate_openapi.py # 验证规范完整性
├── references/
│ ├── openapi_spec.md # OpenAPI 3.1规范详解
│ ├── documentation_best_practices.md
│ └── code_examples.md # 各语言的示例代码模板
└── assets/├── swagger-ui-template/ # Swagger UI模板├── postman-template.json # Postman Collection模板└── markdown-template.md # Markdown文档模板
5.3 Phase 2: 创建Skill内容
5.3.1 步骤1: 初始化Skill框架
# 使用skill-creator的初始化脚本
python scripts/init_skill.py api-doc-generator --path ./my-skills/# 输出:
# ✓ 创建目录: ./my-skills/api-doc-generator
# ✓ 生成SKILL.md模板
# ✓ 创建scripts/目录并添加示例
# ✓ 创建references/目录
# ✓ 创建assets/目录
5.3.2 步骤2: 编写SKILL.md
---
name: api-doc-generator
description: 系统化生成RESTful API文档，支持多种框架（Flask、FastAPI、Express）和输出格式（OpenAPI、Markdown、Postman）。适用于需要创建、更新或标准化API文档的场景。
license: Apache 2.0
allowed-tools:- read_file- write- run_terminal_cmd
---# API Documentation Generator## 概述该技能帮助系统化地生成高质量API文档。支持从代码分析、手动输入或API响应样本生成文档。## 使用场景触发该技能的典型请求：
- "分析这个Flask项目并生成API文档"
- "根据这些API端点创建OpenAPI规范"
- "生成Postman Collection用于测试"
- "创建交互式API文档"## 工作流决策树### 场景1: 从代码分析生成
**适用:** 有源代码访问权限#### 步骤
1. **识别框架**```bash# 检查项目类型grep -r "from flask import" .grep -r "from fastapi import" .grep -r "express()" .
-
解析路由 - 根据框架选择脚本
-
Flask →
python scripts/parse_flask_routes.py -
FastAPI →
python scripts/parse_fastapi_routes.py -
Express → 手动分析（见下文）
-
-
生成OpenAPI规范
python scripts/generate_openapi.py \--routes routes.json \--output openapi.yaml \--title "My API" \--version "1.0.0" -
验证完整性
python scripts/validate_openapi.py openapi.yaml如果有警告，补充缺失信息（描述、示例等）
-
生成多种格式
-
Markdown文档（见"生成Markdown"节）
-
Swagger UI（见"部署交互文档"节）
-
Postman Collection（见"生成Postman"节）
-
场景2: 从API响应生成
适用: 无源代码但能调用API
步骤
-
收集端点信息 让用户提供或自己调用API收集：
-
端点URL
-
HTTP方法
-
请求/响应示例
-
认证方式
-
-
手动构建OpenAPI - 读取模板
加载 references/openapi_spec.md 了解结构 -
使用交互式方法
# 为每个端点问： endpoint = "/users/{id}" method = "GET"# 从响应样本推断schema response_sample = {...} schema = infer_schema(response_sample) -
生成文档 - 同场景1步骤5
场景3: 更新现有文档
适用: 已有OpenAPI规范需要更新
步骤
-
加载现有规范
python scripts/validate_openapi.py existing_openapi.yaml -
识别变更
-
新增端点
-
修改的参数
-
新的响应状态码
-
-
合并更新
# 使用generate_openapi.py的--merge模式 python scripts/generate_openapi.py \--routes new_routes.json \--merge existing_openapi.yaml \--output updated_openapi.yaml
辅助工作流
生成Markdown文档
# 从OpenAPI生成人类友好的Markdown
python scripts/openapi_to_markdown.py openapi.yaml \--template assets/markdown-template.md \--output API_DOCS.md
Markdown模板支持：
-
按标签（tags）分组端点
-
代码示例（curl、Python、JavaScript）
-
响应示例
-
认证说明
部署交互式文档
# 使用Swagger UI模板
python scripts/init_doc_project.py \--swagger-ui \--spec openapi.yaml \--output ./docs# 启动本地服务器预览
cd docs && python -m http.server 8000
# 访问 http://localhost:8000
生成Postman Collection
# 转换OpenAPI为Postman格式
python scripts/generate_postman.py openapi.yaml \--output postman_collection.json \--add-examples \--add-tests
最佳实践
描述编写指南
生成的文档质量取决于描述的详细程度。遵循：
-
端点描述 - 说明用途和业务逻辑
summary: "获取用户信息" description: |根据用户ID获取详细信息。需要认证。返回用户的基本资料、角色和最后登录时间。 -
参数描述 - 解释含义和约束
parameters:- name: iddescription: "用户的唯一标识符（UUID v4格式）"required: trueschema:type: stringformat: uuid -
响应说明 - 涵盖所有状态码
responses:200:description: "成功返回用户信息"404:description: "用户不存在"401:description: "未认证或token过期"
代码示例模板
为每个端点生成多语言示例。加载 references/code_examples.md 查看模板。
常见语言：
-
cURL（命令行测试）
-
Python（requests库）
-
JavaScript（fetch API）
-
Java（OkHttp）
版本控制策略
API文档应与代码同步：
-
在CI/CD中集成
# .github/workflows/docs.yml - name: Generate API docsrun: |python scripts/generate_openapi.py --autogit add openapi.yamlgit commit -m "docs: update API spec" -
语义化版本
-
新增端点 → minor version
-
修改响应结构 → major version
-
修复描述 → patch version
-
故障排查
常见问题
问题： parse_flask_routes.py报错"No routes found" 解决： 确保Flask应用实例可导入
# 在项目根目录确保有__init__.py
# 且Flask app为全局变量：app = Flask(__name__)
问题： 生成的OpenAPI规范验证失败 解决： 运行详细验证
python scripts/validate_openapi.py openapi.yaml --verbose
# 查看具体缺失字段，逐一补充
问题： Swagger UI无法加载 解决： 检查CORS设置和文件路径
# 确保openapi.yaml路径正确
# 检查浏览器控制台的错误信息
技术细节
框架特定的注意事项
Flask
-
支持函数式和类视图（MethodView）
-
自动提取docstring作为描述
-
处理Flask-RESTful的Resource类
FastAPI
-
原生Pydantic模型自动转OpenAPI
-
支持依赖注入的参数推断
-
处理响应模型和status_code
Express
-
需要手动解析路由定义
-
识别常见中间件（body-parser、cors）
-
从JSDoc注释提取描述
参考资料
需要详细信息时，加载这些文件：
-
OpenAPI规范 -
references/openapi_spec.md（OpenAPI 3.1完整规范） -
最佳实践 -
references/documentation_best_practices.md（业界标准） -
代码示例 -
references/code_examples.md（多语言模板）
依赖项
在使用前确保安装：
pip install pyyaml jsonschema jinja2 requests
对于框架特定的解析：
pip install flask fastapi # 根据需要
#### 5.3.3 步骤3: 实现核心脚本**scripts/parse_flask_routes.py**```python
#!/usr/bin/env python3
"""
解析Flask应用的路由并生成结构化JSON。用法:python parse_flask_routes.py <module:app> [--output routes.json]示例:python parse_flask_routes.py myapp:app --output routes.json
"""import sys
import json
import importlib
import argparse
from typing import Dict, List, Anydef extract_flask_routes(app) -> List[Dict[str, Any]]:"""提取Flask app的所有路由信息"""routes = []for rule in app.url_map.iter_rules():# 跳过静态文件路由if rule.endpoint == 'static':continue# 获取视图函数view_func = app.view_functions[rule.endpoint]# 提取docstring作为描述description = view_func.__doc__ or ""# 处理每个HTTP方法for method in rule.methods:if method in ['HEAD', 'OPTIONS']:continueroute_info = {'path': str(rule),'method': method,'endpoint': rule.endpoint,'description': description.strip(),'parameters': extract_parameters(rule),'function_name': view_func.__name__}routes.append(route_info)return routesdef extract_parameters(rule) -> List[Dict[str, str]]:"""从路由规则提取路径参数"""params = []for arg in rule.arguments:param = {'name': arg,'in': 'path','required': True,'type': 'string' # 默认，可后续优化}params.append(param)return paramsdef main():parser = argparse.ArgumentParser(description='解析Flask应用路由')parser.add_argument('app',help='Flask应用导入路径（格式：module:variable）')parser.add_argument('--output', '-o',default='routes.json',help='输出JSON文件路径')args = parser.parse_args()# 导入Flask应用try:module_name, app_name = args.app.split(':')module = importlib.import_module(module_name)app = getattr(module, app_name)except Exception as e:print(f"错误：无法导入 {args.app}", file=sys.stderr)print(f"详情：{str(e)}", file=sys.stderr)sys.exit(1)# 提取路由routes = extract_flask_routes(app)# 保存为JSONwith open(args.output, 'w', encoding='utf-8') as f:json.dump(routes, f, indent=2, ensure_ascii=False)print(f"✓ 成功解析 {len(routes)} 个路由")print(f"✓ 已保存到 {args.output}")if __name__ == '__main__':main()
scripts/generate_openapi.py
#!/usr/bin/env python3
"""
从路由JSON生成OpenAPI 3.1规范。用法:python generate_openapi.py --routes routes.json --output openapi.yaml选项:--title API标题--version API版本--description API描述--server 服务器URL
"""import json
import yaml
import argparse
from typing import Dict, Anydef create_openapi_template(title: str,version: str,description: str,server_url: str
) -> Dict[str, Any]:"""创建基础OpenAPI结构"""return {'openapi': '3.1.0','info': {'title': title,'version': version,'description': description},'servers': [{'url': server_url}],'paths': {},'components': {'schemas': {},'securitySchemes': {}}}def convert_route_to_openapi_path(route: Dict[str, Any]) -> Dict[str, Any]:"""将路由信息转为OpenAPI path item"""operation = {'summary': route.get('description', '').split('\n')[0],'description': route.get('description', ''),'operationId': f"{route['method'].lower()}_{route['endpoint']}",'parameters': [],'responses': {'200': {'description': '成功','content': {'application/json': {'schema': {'type': 'object','properties': {}}}}}}}# 转换参数for param in route.get('parameters', []):operation['parameters'].append({'name': param['name'],'in': param['in'],'required': param.get('required', True),'schema': {'type': param.get('type', 'string')}})return operationdef main():parser = argparse.ArgumentParser(description='生成OpenAPI规范')parser.add_argument('--routes', required=True,help='路由JSON文件')parser.add_argument('--output', required=True,help='输出YAML文件')parser.add_argument('--title', default='My API',help='API标题')parser.add_argument('--version', default='1.0.0',help='API版本')parser.add_argument('--description', default='API Documentation',help='API描述')parser.add_argument('--server', default='http://localhost:5000',help='服务器URL')args = parser.parse_args()# 加载路由with open(args.routes, 'r', encoding='utf-8') as f:routes = json.load(f)# 创建OpenAPI文档openapi_doc = create_openapi_template(args.title, args.version, args.description, args.server)# 转换每个路由for route in routes:path = route['path']method = route['method'].lower()if path not in openapi_doc['paths']:openapi_doc['paths'][path] = {}openapi_doc['paths'][path][method] = \convert_route_to_openapi_path(route)# 保存为YAMLwith open(args.output, 'w', encoding='utf-8') as f:yaml.dump(openapi_doc, f, default_flow_style=False,allow_unicode=True, sort_keys=False)print(f"✓ 成功生成OpenAPI规范")print(f"✓ 包含 {len(openapi_doc['paths'])} 个路径")print(f"✓ 已保存到 {args.output}")if __name__ == '__main__':main()
5.3.4 步骤4: 编写Reference文档
references/openapi_spec.md（精简版）
# OpenAPI 3.1 规范速查## 基础结构```yaml
openapi: 3.1.0
info:title: API标题version: 1.0.0description: API描述contact:name: 维护者email: api@example.comservers:- url: https://api.example.com/v1description: 生产环境- url: http://localhost:5000description: 开发环境paths:/users:get:summary: 获取用户列表# ... 详见下文
Path Item结构
每个路径可包含HTTP方法：
/users/{id}:get:summary: 获取单个用户operationId: getUserparameters:- name: idin: pathrequired: trueschema:type: stringresponses:200:description: 成功content:application/json:schema:$ref: '#/components/schemas/User'404:description: 用户不存在
参数类型
参数可以在以下位置：
-
path - 路径参数（必需）
-
query - 查询字符串
-
header - 请求头
-
cookie - Cookie
示例：
parameters:- name: id # 路径参数in: pathrequired: trueschema:type: integer- name: limit # 查询参数in: queryrequired: falseschema:type: integerdefault: 20minimum: 1maximum: 100
Schema定义
使用JSON Schema定义数据结构：
components:schemas:User:type: objectrequired:- id- emailproperties:id:type: integerexample: 42email:type: stringformat: emailexample: user@example.comcreated_at:type: stringformat: date-time
安全认证
常见认证方式：
components:securitySchemes:BearerAuth:type: httpscheme: bearerbearerFormat: JWTApiKeyAuth:type: apiKeyin: headername: X-API-KeyOAuth2:type: oauth2flows:authorizationCode:authorizationUrl: https://example.com/oauth/authorizetokenUrl: https://example.com/oauth/tokenscopes:read: 读取权限write: 写入权限# 在operation中应用
paths:/protected:get:security:- BearerAuth: []
响应示例
提供详细的响应示例提高文档可读性：
responses:200:description: 成功content:application/json:schema:$ref: '#/components/schemas/User'examples:normal_user:summary: 普通用户value:id: 42email: user@example.comrole: useradmin_user:summary: 管理员value:id: 1email: admin@example.comrole: admin
最佳实践
1. 使用$ref减少重复
# 定义一次
components:parameters:PageLimit:name: limitin: queryschema:type: integerdefault: 20# 多处引用
paths:/users:get:parameters:- $ref: '#/components/parameters/PageLimit'/posts:get:parameters:- $ref: '#/components/parameters/PageLimit'
2. 详细的描述
-
使用Markdown格式
-
说明业务含义，不仅是技术细节
-
包含边界情况和错误场景
3. 实际的示例
-
使用真实数据格式
-
涵盖常见和边缘情况
-
保持一致性
4. 语义化版本
-
重大变更 → 主版本号
-
新增功能 → 次版本号
-
修复bug → 修订号
#### 5.3.5 步骤5: 准备Assets**assets/markdown-template.md**```markdown
# {{api_title}}**Version:** {{api_version}}
**Base URL:** {{server_url}}{{api_description}}## 认证{{#if authentication}}
该API使用以下认证方式：
{{#each auth_schemes}}
- **{{name}}**: {{description}}
{{/each}}
{{/if}}---## 端点{{#each endpoints}}
### {{method}} {{path}}**描述:** {{description}}{{#if parameters}}
#### 参数| 名称 | 位置 | 类型 | 必需 | 描述 |
|------|------|------|------|------|
{{#each parameters}}
| `{{name}}` | {{in}} | {{type}} | {{#if required}}是{{else}}否{{/if}} | {{description}} |
{{/each}}
{{/if}}#### 请求示例```bash
# cURL
curl -X {{method}} "{{server_url}}{{path_example}}" \-H "Content-Type: application/json" \{{#if auth}}-H "Authorization: Bearer YOUR_TOKEN"{{/if}}
# Python (requests)
import requestsresponse = requests.{{method_lower}}("{{server_url}}{{path_example}}",headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(response.json())
响应示例
{{response_example}}
{{/each}}
错误代码
| 状态码 | 含义 |
|---|---|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
变更日志
{{api_version}}
-
初始版本发布
### 5.4 Phase 3: 测试与迭代#### 5.4.1 单元测试脚本创建`tests/test_parse_flask.py`：```python
import pytest
from flask import Flask
from scripts.parse_flask_routes import extract_flask_routesdef test_basic_route_extraction():"""测试基础路由提取"""app = Flask(__name__)@app.route('/users', methods=['GET'])def get_users():"""获取所有用户"""pass@app.route('/users/<int:id>', methods=['GET'])def get_user(id):"""获取单个用户"""passroutes = extract_flask_routes(app)assert len(routes) == 2assert routes[0]['path'] == '/users'assert routes[0]['method'] == 'GET'assert routes[1]['path'] == '/users/<int:id>'assert '用户' in routes[1]['description']def test_parameter_extraction():"""测试参数提取"""app = Flask(__name__)@app.route('/posts/<int:post_id>/comments/<int:comment_id>')def get_comment(post_id, comment_id):passroutes = extract_flask_routes(app)params = routes[0]['parameters']assert len(params) == 2assert params[0]['name'] == 'post_id'assert params[1]['name'] == 'comment_id'assert all(p['in'] == 'path' for p in params)
5.4.2 集成测试
创建一个测试项目：
# test_project/app.py
from flask import Flask, jsonifyapp = Flask(__name__)@app.route('/api/users', methods=['GET'])
def list_users():"""获取用户列表返回系统中所有注册用户。支持分页和过滤。"""return jsonify([{"id": 1, "name": "Alice"}])@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):"""根据ID获取单个用户的详细信息"""return jsonify({"id": user_id, "name": "Alice"})if __name__ == '__main__':app.run()
运行完整流程：
# 1. 解析路由
python scripts/parse_flask_routes.py test_project.app:app \--output test_routes.json# 2. 生成OpenAPI
python scripts/generate_openapi.py \--routes test_routes.json \--output test_openapi.yaml \--title "Test API" \--version "1.0.0"# 3. 验证结果
python scripts/validate_openapi.py test_openapi.yaml# 预期输出：
# ✓ OpenAPI结构有效
# ✓ 所有路径定义完整
# ⚠ 建议添加更多响应状态码（404, 500等）
# ⚠ 建议添加认证信息
5.4.3 与Claude交互测试
现在，真正的测试来了——让Claude使用这个Skill：
# 对话测试
用户: "帮我为这个Flask项目生成API文档"
[附上test_project/app.py代码]Claude加载api-doc-generator技能:"我将使用api-doc-generator技能来系统化地生成文档。【决策】识别到这是Flask项目，选择'从代码分析生成'工作流【步骤1】解析Flask路由
执行: python scripts/parse_flask_routes.py test_project.app:app【步骤2】生成OpenAPI规范
执行: python scripts/generate_openapi.py --routes routes.json ...【步骤3】创建Markdown文档
根据assets/markdown-template.md生成人类可读文档【步骤4】部署交互式文档
执行: python scripts/init_doc_project.py --swagger-ui ...✓ 已生成以下文件：
- openapi.yaml (OpenAPI 3.1规范)
- API_DOCS.md (Markdown文档)
- docs/ (Swagger UI交互式文档)你可以运行 `cd docs && python -m http.server 8000` 查看交互式文档。"
5.5 Phase 4: 打包与发布
5.5.1 质量检查
使用skill-creator的验证脚本：
python scripts/package_skill.py ./api-doc-generator# 输出：
# [验证] 检查SKILL.md格式...
# ✓ YAML前置元数据有效
# ✓ name与目录名匹配
# ✓ description详细且完整（187字）
#
# [验证] 检查文件组织...
# ✓ scripts/中所有脚本有执行权限
# ✓ references/中所有文件被SKILL.md引用
# ✓ 无未使用的assets
#
# [验证] 检查代码质量...
# ✓ 所有Python脚本通过语法检查
# ✓ 所有脚本有--help选项
# ✓ 错误处理完善
#
# [打包] 创建分发包...
# ✓ 已创建 api-doc-generator.zip
#
# 🎉 Skill验证通过并已打包！
5.5.2 文档完善
创建api-doc-generator/README.md：
# API Documentation Generator Skill## 功能特性- ✅ 支持多框架（Flask、FastAPI、Express）
- ✅ 生成OpenAPI 3.1标准规范
- ✅ 多格式输出（YAML、JSON、Markdown）
- ✅ 交互式Swagger UI
- ✅ Postman Collection导出
- ✅ 多语言代码示例## 快速开始### 安装将`api-doc-generator.zip`上传到Claude：1. Claude.ai: Skills → Upload Custom Skill
2. Claude Code: `/plugin install api-doc-generator.zip`
3. API: 使用Skills API上传### 使用示例**示例1: 分析Flask项目**
"帮我分析这个Flask项目并生成完整的API文档" [附上代码]
**示例2: 从API响应生成**
"我有这些API端点的响应样本，帮我生成OpenAPI规范：
-
GET /users → [{"id":1,"name":"Alice"}]
-
POST /users → {"id":2,"name":"Bob"} ..."
## 支持的框架| 框架 | 支持程度 | 特性 |
|------|---------|------|
| Flask | ✅ 完全 | 自动提取docstring、参数 |
| FastAPI | ✅ 完全 | Pydantic模型自动转换 |
| Express | ⚠️ 手动 | 需手动解析路由 |
| Django | 🚧 计划中 | 未来支持 |## 依赖项```bash
pip install pyyaml jsonschema jinja2 requests
贡献
欢迎提交PR改进该Skill！
许可证
Apache 2.0
---## 第六章：企业级应用场景Skills系统的真正威力，在企业环境中才能完全展现。让我们探讨几个深度场景。### 6.1 场景1：智能代码审查助手**业务挑战：**
- 代码审查耗时（平均2-4小时/PR）
- 审查质量不一致
- 新人不熟悉最佳实践
- 安全漏洞容易遗漏**Skill解决方案：code-review-assistant**```markdown
## 技能结构code-review-assistant/
├── SKILL.md
├── scripts/
│ ├── static_analysis.py # 运行多个静态分析工具
│ ├── security_scan.py # 安全漏洞扫描
│ ├── complexity_analysis.py # 代码复杂度分析
│ └── generate_review_report.py # 生成审查报告
├── references/
│ ├── coding_standards.md # 公司编码规范
│ ├── security_checklist.md # 安全检查清单
│ ├── design_patterns.md # 推荐设计模式
│ └── common_pitfalls.md # 常见陷阱
└── assets/└── review_templates/ # 审查报告模板
工作流设计：
## 代码审查工作流### Phase 1: 自动化检查
1. 运行静态分析（pylint, mypy, eslint等）
2. 安全扫描（bandit, semgrep）
3. 复杂度分析（圈复杂度、认知复杂度）
4. 测试覆盖率检查### Phase 2: 规范审查
加载 `references/coding_standards.md`，检查：
- 命名规范
- 代码组织
- 注释完整性
- 错误处理### Phase 3: 设计审查
加载 `references/design_patterns.md`，评估：
- 是否使用适当的设计模式
- SOLID原则遵循情况
- 可维护性和扩展性### Phase 4: 安全审查
加载 `references/security_checklist.md`，检查：
- SQL注入风险
- XSS漏洞
- 敏感数据处理
- 认证/授权逻辑### Phase 5: 生成报告
使用 `scripts/generate_review_report.py` 创建：
- 问题分类（Critical/High/Medium/Low）
- 修复建议（包含代码示例）
- 学习资源链接
实际效果：
# 原始PR代码
def get_user(user_id):user = db.execute(f"SELECT * FROM users WHERE id = {user_id}")return user# Claude使用code-review-assistant后的反馈："""
## 安全审查 - CRITICAL### 🚨 SQL注入漏洞 (Line 2)**问题：** 使用字符串拼接构造SQL，存在SQL注入风险**风险等级：** Critical**攻击示例：**
user_id = "1; DROP TABLE users; --"
→ 执行: SELECT * FROM users WHERE id = 1; DROP TABLE users; --**修复建议：**
```python
def get_user(user_id):# 使用参数化查询user = db.execute("SELECT * FROM users WHERE id = ?",(user_id,))return user
参考： references/security_checklist.md#sql-injection
设计审查 - MEDIUM
💡 缺少错误处理 (Line 2-3)
问题： 用户不存在时会返回None，调用方可能未处理
改进建议：
def get_user(user_id):user = db.execute("SELECT * FROM users WHERE id = ?",(user_id,))if not user:raise UserNotFoundError(f"User {user_id} does not exist")return user
代码规范 - LOW
📝 缺少类型提示和文档 (Line 1)
建议： 添加类型提示和docstring提高可维护性
from typing import Dict, Anydef get_user(user_id: int) -> Dict[str, Any]:\"\"\"根据ID获取用户信息。Args:user_id: 用户唯一标识符Returns:包含用户信息的字典Raises:UserNotFoundError: 用户不存在时\"\"\"...
"""
### 6.2 场景2：智能数据分析师**业务挑战：**
- 业务人员不懂SQL
- 数据分析需求频繁变化
- 需要多维度交叉分析
- 可视化需求多样**Skill解决方案：data-analyst-pro**```markdown
data-analyst-pro/
├── SKILL.md
├── scripts/
│ ├── query_optimizer.py # SQL优化
│ ├── data_profiler.py # 数据概览
│ ├── statistical_analysis.py # 统计分析
│ └── visualization_engine.py # 可视化生成
├── references/
│ ├── database_schema.md # 数据库schema文档
│ ├── business_metrics.md # 业务指标定义
│ ├── statistical_methods.md # 统计方法指南
│ └── visualization_guide.md # 可视化最佳实践
└── assets/└── chart_templates/ # Plotly/Matplotlib模板
交互示例：
用户: "过去三个月，哪个产品类别的复购率最高？给我前10名"Claude (使用data-analyst-pro):"我将使用data-analyst-pro技能进行系统化分析。【理解需求】
- 时间范围：过去3个月
- 分析维度：产品类别
- 指标：复购率 (repeat_purchase_rate)
- 输出：Top 10【加载schema】
读取 references/database_schema.md
识别相关表：
- orders (order_id, user_id, product_id, created_at)
- products (product_id, category)
- users (user_id)【加载业务定义】
读取 references/business_metrics.md
复购率定义：
repeat_purchase_rate = (购买次数≥2的用户数) / (总购买用户数)【生成SQL】
```sql
WITH purchase_counts AS (SELECT p.category,o.user_id,COUNT(DISTINCT o.order_id) as purchase_countFROM orders oJOIN products p ON o.product_id = p.product_idWHERE o.created_at >= DATE_SUB(NOW(), INTERVAL 3 MONTH)GROUP BY p.category, o.user_id
),
category_stats AS (SELECTcategory,COUNT(DISTINCT user_id) as total_users,SUM(CASE WHEN purchase_count >= 2 THEN 1 ELSE 0 END) as repeat_usersFROM purchase_countsGROUP BY category
)
SELECTcategory,total_users,repeat_users,ROUND(repeat_users * 100.0 / total_users, 2) as repeat_purchase_rate
FROM category_stats
ORDER BY repeat_purchase_rate DESC
LIMIT 10;
【执行查询】 运行 scripts/query_optimizer.py 检查性能 → 建议添加索引：CREATE INDEX idx_orders_created_at ON orders(created_at)
【结果分析】
| 类别 | 总用户数 | 复购用户 | 复购率 |
|---|---|---|---|
| 零食饮料 | 5420 | 3891 | 71.79% |
| 个护美妆 | 4832 | 3251 | 67.28% |
| ... |
【生成可视化】 使用 scripts/visualization_engine.py 创建交互式柱状图（Plotly）
【洞察提炼】
-
零食饮料复购率最高（71.79%），说明是刚需品类
-
前3名复购率均超过65%，可作为流量入口
-
建议：增加这些类别的库存和促销活动
[附上可视化图表] "
### 6.3 场景3：合规性检查自动化**业务挑战：**
- GDPR/CCPA等法规复杂
- 人工检查易遗漏
- 不同地区要求不同
- 需定期审计**Skill解决方案：compliance-checker**```markdown
compliance-checker/
├── SKILL.md
├── scripts/
│ ├── scan_pii.py # 扫描个人信息
│ ├── check_data_retention.py # 数据保留策略检查
│ ├── audit_access_logs.py # 访问日志审计
│ └── generate_compliance_report.py
├── references/
│ ├── gdpr_requirements.md # GDPR详细要求
│ ├── ccpa_requirements.md # CCPA详细要求
│ ├── hipaa_requirements.md # HIPAA详细要求
│ └── data_classification.md # 数据分类标准
└── assets/└── compliance_templates/ # 合规报告模板
核心能力：
-
PII检测
# scripts/scan_pii.py核心逻辑 def scan_for_pii(codebase_path):"""扫描代码中的PII处理"""pii_patterns = {'email': r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b','ssn': r'\b\d{3}-\d{2}-\d{4}\b','credit_card': r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b',# ... 更多模式}findings = []for file in scan_files(codebase_path):# 检查是否有PII处理# 验证是否有适当的加密# 检查日志中是否泄露PII... -
数据保留检查
def check_retention_policy(database):"""检查数据保留是否符合政策"""for table in database.tables:retention_days = get_retention_policy(table)old_records = count_records_older_than(table, retention_days)if old_records > 0:yield ComplianceIssue(severity='HIGH',message=f"{table}中有{old_records}条记录超过保留期限",regulation='GDPR Article 5(1)(e)',remediation='执行数据删除或归档')
第七章：高级技巧与最佳实践
7.1 技巧1：Skills的版本管理
挑战： Skill会随业务变化需要更新，如何管理版本？
方案：语义化版本 + 变更日志
# SKILL.md
---
name: api-doc-generator
version: 2.1.0 # 添加version字段
description: ...
changelog_url: https://github.com/mycompany/skills/blob/main/CHANGELOG.md
---## 版本历史### 2.1.0 (2024-01-15)
- 新增FastAPI完整支持
- 改进OpenAPI 3.1生成质量
- 修复路径参数提取bug### 2.0.0 (2023-12-01) - BREAKING CHANGE
- 重构为模块化结构
- ⚠️ 移除对Flask 1.x的支持
- 迁移指南：见 references/migration_v2.md### 1.5.2 (2023-11-20)
- 修复Swagger UI模板bug
实践建议：
-
主版本号：破坏性变更（工作流改变、脚本接口变更）
-
次版本号：新增功能（新的工作流、新的脚本）
-
修订号：bug修复（不改变行为）
7.2 技巧2：Skills的测试策略
三层测试金字塔：
/\/ \ End-to-End Tests/____\ (与Claude交互测试)/ \/ Integration\ Tests/___________\ (脚本集成测试)/ \/ Unit Tests \
/___________________\
(脚本单元测试)
E2E测试示例：
# tests/e2e/test_api_doc_generator.py
import anthropicdef test_full_workflow():"""测试完整的文档生成工作流"""client = anthropic.Anthropic(api_key="...")# 上传Skillskill_id = client.skills.create(skill_folder="./api-doc-generator")# 创建测试对话response = client.messages.create(model="claude-3-5-sonnet-20241022",max_tokens=4096,skills=[skill_id],messages=[{"role": "user","content": """帮我为这个Flask项目生成API文档：```pythonfrom flask import Flaskapp = Flask(__name__)@app.route('/users')def get_users():\"\"\"获取用户列表\"\"\"pass```"""}])# 验证结果assert "openapi.yaml" in response.content[0].textassert "✓ 成功生成OpenAPI规范" in response.content[0].text# 验证生成的文件# (需要Claude Code环境或文件系统访问)
7.3 技巧3：Skills的调试
挑战： AI使用Skill时出错，如何调试？
方案1：详细日志
在SKILL.md中嵌入调试指令：
## 调试模式当遇到问题时，启用详细日志：```bash
export DEBUG=1
python scripts/parse_flask_routes.py --verbose myapp:app
日志将输出：
-
每个步骤的详细信息
-
中间结果
-
错误堆栈
**方案2：干运行模式**```python
# scripts/generate_openapi.py添加--dry-run
parser.add_argument('--dry-run', action='store_true',help='只显示将要执行的操作，不实际生成文件')if args.dry_run:print("【干运行模式】将执行以下操作：")print(f"1. 加载 {args.routes}")print(f"2. 解析 {len(routes)} 个路由")print(f"3. 生成OpenAPI规范到 {args.output}")print("（实际文件未生成）")return
方案3：检查点系统
# 在长流程中保存中间结果
def generate_documentation(project_path):# Checkpoint 1: 解析完成routes = parse_routes(project_path)save_checkpoint('routes.json', routes)# Checkpoint 2: OpenAPI生成openapi = generate_openapi(routes)save_checkpoint('openapi.yaml', openapi)# Checkpoint 3: 文档生成docs = generate_markdown(openapi)save_checkpoint('docs.md', docs)
如果失败，可以从checkpoint恢复：
# 从第2步继续
python scripts/generate_openapi.py \--from-checkpoint routes.json \--skip-parse
7.4 技巧4：Skills的性能优化
问题： 复杂Skill可能导致响应变慢
优化策略：
1. 懒加载References
<!-- 不好：一次性加载所有 -->
## 准备工作
首先阅读以下所有文件：
- references/python_guide.md (5000行)
- references/typescript_guide.md (5000行)
- references/java_guide.md (5000行)<!-- 好：按需加载 -->
## 准备工作
根据项目语言，加载对应指南：
- Python项目 → 加载 references/python_guide.md
- TypeScript项目 → 加载 references/typescript_guide.md
- Java项目 → 加载 references/java_guide.md
2. 脚本预编译
# 对于频繁调用的Python脚本，使用.pyc加速
python -m compileall scripts/# 对于大型依赖，使用虚拟环境
# 在Skill中包含requirements.txt
pip install -r requirements.txt
3. 缓存机制
# scripts/with_cache.py
import functools
import hashlib
import pickledef cached_result(cache_dir='.skill_cache'):def decorator(func):@functools.wraps(func)def wrapper(*args, **kwargs):# 计算参数hash作为缓存键key = hashlib.md5(pickle.dumps((args, kwargs))).hexdigest()cache_file = f"{cache_dir}/{func.__name__}_{key}.pkl"if os.path.exists(cache_file):with open(cache_file, 'rb') as f:return pickle.load(f)# 执行函数result = func(*args, **kwargs)# 保存缓存os.makedirs(cache_dir, exist_ok=True)with open(cache_file, 'wb') as f:pickle.dump(result, f)return resultreturn wrapperreturn decorator@cached_result()
def expensive_analysis(codebase_path):"""耗时的代码分析，结果会被缓存"""...
7.5 技巧5：跨Skill协作
场景： 一个任务需要多个Skills配合
设计模式：Master-Worker
创建一个"orchestrator" Skill来协调其他Skills：
# project-builder/SKILL.md
---
name: project-builder
description: 编排多个技能完成完整项目创建
---## 工作流创建一个新项目需要协调多个技能：### Phase 1: 项目结构 (使用skill-creator)
"使用skill-creator技能创建项目骨架"
→ 调用skill-creator
→ 获得基础目录结构### Phase 2: 生成代码 (使用artifacts-builder或webapp-testing)
"根据项目类型，使用相应技能生成代码"
→ Web前端 → 调用artifacts-builder
→ API服务 → 自行生成
→ 测试 → 调用webapp-testing### Phase 3: 生成文档 (使用api-doc-generator)
"为API生成文档"
→ 调用api-doc-generator
→ 生成OpenAPI规范和Markdown文档### Phase 4: 设置CI/CD (自行处理)
"创建.github/workflows/或.gitlab-ci.yml"
→ 使用本技能的templates### Phase 5: 创建README (使用canvas-design可选)
"生成README.md"
→ 可选：使用canvas-design生成项目logo
实际使用：
用户: "帮我创建一个完整的Todo API项目，包括代码、文档、测试和CI/CD"Claude (加载project-builder):
"我将使用project-builder技能来编排这个复杂任务。【Phase 1】创建项目结构...
→ 使用skill-creator
✓ 已创建 todo-api/ 目录结构【Phase 2】生成API代码...
✓ 创建Flask应用
✓ 实现CRUD端点
✓ 添加数据库模型【Phase 3】生成API文档...
→ 使用api-doc-generator
✓ 生成openapi.yaml
✓ 创建交互式文档【Phase 4】编写测试...
→ 使用webapp-testing技能
✓ 创建Pytest测试套件
✓ 覆盖率达到85%【Phase 5】设置CI/CD...
✓ 创建GitHub Actions工作流
✓ 包含测试、linting、部署【Phase 6】生成README...
✓ 包含安装说明、API文档链接、贡献指南🎉 项目创建完成！目录结构：
[显示完整的文件树]
"
第八章：未来展望与生态建设
8.1 Skills的生态愿景
Skills系统才刚刚起步，但已经展现出建立一个庞大生态的潜力，类似于：
-
VSCode插件生态 - 百万开发者贡献插件
-
npm包生态 - 200万+包
-
Chrome扩展生态 - 数十万扩展
Skills生态可能的发展路径：
2024 Q4: 官方示例Skills (当前阶段)↓
2025 Q1: 社区Skills市场- 开发者上传自定义Skills- 评分和评论系统- 版本管理↓
2025 Q2: Skills工具链成熟- Skill开发IDE插件- 自动化测试框架- 性能分析工具↓
2025 Q3: 企业级Skills管理- 私有Skill仓库- 团队协作开发- 合规性审计↓
2025 Q4: Skills标准化- 跨AI平台兼容- Skills互操作协议- 统一的Skill描述语言
8.2 技术趋势预测
趋势1：从静态到动态
当前Skills是静态的（文件夹+脚本），未来可能支持：
# 动态Skill：可以从API获取最新信息
class DynamicSkill:def load(self):# 从远程服务器获取最新的工作流定义workflow = fetch_from_api("https://skills.company.com/api-doc-gen")return workflowdef update(self):# 自动检测并更新到最新版本if self.check_updates():self.load()
趋势2：从手工到AI生成
未来可能出现"Skill生成器"——用AI生成Skills：
用户: "帮我创建一个专门处理公司财务报表的Skill"AI分析:
1. 识别领域：财务报表
2. 收集知识：会计准则、税法、公司政策
3. 设计工作流：数据提取 → 验证 → 分析 → 报告生成
4. 生成Scripts：使用pandas、openpyxl等
5. 创建References：从公司文档提取
6. 打包Skill输出: finance-report-analyzer.zip
趋势3：从单机到协作
Skills可能支持跨实例协作：
Claude实例A (加载code-review-assistant):
"我负责安全审查部分"Claude实例B (加载performance-analyzer):
"我负责性能分析部分"Claude实例C (协调者):
"整合两者的结果生成综合报告"
8.3 与其他技术的融合
Skills + MCP = 完整的AI Agent能力体系
┌─────────────────────────────────────────┐
│ AI Agent完整能力 │
├─────────────────────────────────────────┤
│ │
│ Knowledge & Workflow (Skills) │
│ - 如何做（How） │
│ - 领域知识（Domain Knowledge） │
│ - 最佳实践（Best Practices） │
│ │
├─────────────────────────────────────────┤
│ │
│ Tool Access (MCP) │
│ - 做什么（What） │
│ - 外部服务（External Services） │
│ - 实时数据（Real-time Data） │
│ │
└─────────────────────────────────────────┘
Skills + RAG = 动态知识库
# 未来的Skill可能集成RAG
class RAGEnabledSkill:def __init__(self):self.vector_db = load_vector_database("company_docs")def handle_query(self, query):# 从向量数据库检索相关知识relevant_docs = self.vector_db.search(query, top_k=5)# 结合Skill的静态知识和动态检索的知识combined_knowledge = self.merge(self.static_knowledge,relevant_docs)return self.process(query, combined_knowledge)
8.4 开发者可以做什么
1. 贡献到开源社区
# Fork官方仓库
git clone https://github.com/anthropics/skills.git# 创建你的Skill
cd skills
python scripts/init_skill.py my-awesome-skill# 提交PR
git add my-awesome-skill/
git commit -m "Add: my-awesome-skill for X use case"
git push origin feature/my-awesome-skill
2. 建立企业内部Skill库
company-skills/
├── README.md
├── skills/
│ ├── code-review-assistant/ # 代码审查
│ ├── data-analyst-pro/ # 数据分析
│ ├── compliance-checker/ # 合规检查
│ ├── document-translator/ # 文档翻译
│ └── api-doc-generator/ # API文档
├── templates/ # Skill模板
└── docs/├── development-guide.md # 开发指南└── best-practices.md # 最佳实践
3. 创建Skill开发工具
# skill-devtools: 一个帮助开发Skill的工具包
from skill_devtools import SkillBuilderbuilder = SkillBuilder("my-new-skill")# 交互式创建
builder.prompt_for_metadata() # 引导填写元数据
builder.suggest_structure() # 建议目录结构
builder.generate_boilerplate() # 生成样板代码
builder.validate() # 验证完整性
builder.test() # 运行测试
builder.package() # 打包发布print("✓ Skill开发完成！")
未来已来，只是分布不均。 希望本文能成为你探索这个激动人心领域的指南针。
附录：快速参考
A. Skills项目资源
-
GitHub仓库: https://github.com/anthropics/skills
-
官方文档: https://docs.claude.com/en/docs/build-with-claude/skills
-
Skills规范: agent_skills_spec.md
-
Anthropic博客: https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
B. 常用命令速查
# 初始化新Skill
python scripts/init_skill.py <skill-name> --path <output-dir># 验证Skill
python scripts/package_skill.py <skill-folder># 打包发布
python scripts/package_skill.py <skill-folder> ./dist# 在Claude Code中安装
/plugin install <skill-name>@anthropic-agent-skills# 在Claude.ai中上传
Settings → Skills → Upload Custom Skill
C. SKILL.md模板
---
name: your-skill-name
description: 详细描述该技能的功能和使用场景。用第三人称，说明何时应该使用该技能。
license: Apache 2.0
allowed-tools: # 可选- read_file- write
---# Your Skill Name## 概述
[简要说明技能用途]## 使用场景
[列出触发该技能的典型请求]## 工作流
[详细的分步骤指南]## 最佳实践
[使用建议和注意事项]## 参考资料
[指向references/中的文件]## 依赖项
[所需的外部依赖]
D. 常见问题FAQ
Q1: Skills和Prompts有什么区别？
A: Prompts是一次性的指令，Skills是可复用的能力模块。类比：Prompt像口头指导，Skill像培训手册。
Q2: 一个Skill可以有多大？
A:
-
SKILL.md建议<5k词
-
scripts/无大小限制（可直接执行）
-
references/无限制（按需加载）
-
总大小建议<50MB（考虑传输）
Q3: Skills可以调用网络API吗？
A: 可以通过scripts调用，但不建议在Skills中存储API密钥。对于需要外部API的场景，建议使用MCP。
Q4: 如何处理Skills的更新？
A: 使用语义化版本号，在SKILL.md中包含changelog，破坏性变更时提供迁移指南。
Q5: Skills支持哪些编程语言？
A: Scripts可以用任何语言编写（Python、Bash、Node.js等），只要能在目标环境执行。
Q6: Claude.ai、Claude Code和API中使用Skills有区别吗？
A: 核心机制相同，但：
-
Claude.ai: 通过UI上传，所有付费用户可用
-
Claude Code: 通过插件系统安装，本地执行
-
API: 通过Skills API管理，可编程控制
Q7: 可以在Skills中使用第三方库吗？
A: 可以。在Skill中包含requirements.txt（Python）或package.json（Node.js），Claude会在需要时安装依赖。
Q8: Skills的执行环境是什么？
A:
-
Claude.ai/API: 云端沙箱环境
-
Claude Code: 用户本地环境
-
都支持文件系统访问（受限）
Q9: 如何调试Skills？
A:
-
在scripts中添加详细日志
-
使用--dry-run模式测试
-
创建检查点系统保存中间结果
-
在本地环境单独测试scripts
Q10: Skills可以商业化吗？
A: 可以。Apache 2.0许可证允许商业使用。你可以创建付费的企业级Skills或提供Skills定制服务。
最后，我想说：
我们正站在一个历史性的十字路口。AI已经不再是遥远的未来，而是每天使用的工具。但如何让这个工具更强大、更可靠、更符合我们的需求？答案就在我们手中——通过Skills系统，通过我们的创造力和专业知识。
每一个你创建的Skill，都是在为AI的能力边界添砖加瓦。每一行代码，都是在定义AI与人类协作的新方式。
这是一个让人兴奋的时代，也是一个充满机遇的时代。
让我们一起，用Skills构建AI的未来。
更多AIGC文章
RAG技术全解：从原理到实战的简明指南
更多VibeCoding文章