解锁AI的“职业技能树“：Claude Skills深度技术解析——从原理到实战的完全指南
2025-11-20 11:15:21
文章摘要
AI技能包革命：Claude Skills技术解析 Anthropic开源的Claude Skills项目标志着LLM应用开发的范式转变，通过模块化"技能包"系统让AI获得可插拔的专业能力。
当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 sys
def 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表示**
```bash
pandoc --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.txt
1.4 学习框架文档
Python → 加载python_mcp_server.md
Node → 加载node_mcp_server.md
1.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 httpx
mcp = 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) * 360
color = 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代码修改XML
generate_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获取当前sprint
2. 应用项目管理知识（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: id
description: "用户的唯一标识符（UUID v4格式）"
required: true
schema:
type: string
format: 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 docs
run: |
python scripts/generate_openapi.py --auto
git add openapi.yaml
git 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, Any
def 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']:
continue
route_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 routes
def 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 params
def 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)
# 保存为JSON
with 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, Any
def 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 operation
def 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)
# 保存为YAML
with 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.0
description: API描述
contact:
name: 维护者
email: api@example.com
servers:
- url: https://api.example.com/v1
description: 生产环境
- url: http://localhost:5000
description: 开发环境
paths:
/users:
get:
summary: 获取用户列表
# ... 详见下文
Path Item结构
每个路径可包含HTTP方法：
/users/{id}:
get:
summary: 获取单个用户
operationId: getUser
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
200:
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
404:
description: 用户不存在
参数类型
参数可以在以下位置：
- path - 路径参数（必需）
- query - 查询字符串
- header - 请求头
- cookie - Cookie
示例：
parameters:
- name: id # 路径参数
in: path
required: true
schema:
type: integer
- name: limit # 查询参数
in: query
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 100
Schema定义
使用JSON Schema定义数据结构：
components:
schemas:
User:
type: object
required:
- id
- email
properties:
id:
type: integer
example: 42
email:
type: string
format: email
example: user@example.com
created_at:
type: string
format: date-time
安全认证
常见认证方式：
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
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: 42
email: user@example.com
role: user
admin_user:
summary: 管理员
value:
id: 1
email: admin@example.com
role: admin
最佳实践
1. 使用$ref减少重复
# 定义一次
components:
parameters:
PageLimit:
name: limit
in: query
schema:
type: integer
default: 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 requests
response = 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_routes
def 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):
"""获取单个用户"""
pass
routes = extract_flask_routes(app)
assert len(routes) == 2
assert 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):
pass
routes = extract_flask_routes(app)
params = routes[0]['parameters']
assert len(params) == 2
assert 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, jsonify
app = 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, Any
def 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_count
FROM orders o
JOIN products p ON o.product_id = p.product_id
WHERE o.created_at >= DATE_SUB(NOW(), INTERVAL 3 MONTH)
GROUP BY p.category, o.user_id
),
category_stats AS (
SELECT
category,
COUNT(DISTINCT user_id) as total_users,
SUM(CASE WHEN purchase_count >= 2 THEN 1 ELSE 0 END) as repeat_users
FROM purchase_counts
GROUP BY category
)
SELECT
category,
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 anthropic
def test_full_workflow():
"""测试完整的文档生成工作流"""
client = anthropic.Anthropic(api_key="...")
# 上传Skill
skill_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文档：
```python
from flask import Flask
app = Flask(__name__)
@app.route('/users')
def get_users():
\"\"\"获取用户列表\"\"\"
pass
```
"""
}]
)
# 验证结果
assert "openapi.yaml" in response.content[0].text
assert "✓ 成功生成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 pickle
def 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 result
return wrapper
return 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 workflow
def 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 SkillBuilder
builder = 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的未来。
声明：该内容由作者自行发布，观点内容仅供参考，不代表平台立场；如有侵权，请联系平台删除。
标签：
