claudeskills文档Skill Creator 技能创建指南
Agent Skill 生命周期手册：帮助梳理范围、结构与打包方式，附带脚本、参考资料与资产。
来源：基于 anthropics/skills（MIT）内容改写。
此技能用于指导如何创建高效的 Claude Skill。
关于 Skill
Skill 是可扩展 Claude 能力的模块化自包含包，提供特定领域的流程、知识与工具。可以把它们看作某个领域的“入职手册”，让 Claude 从通用 Agent 变成精通特定任务的专家。
Skill 能提供什么
- 专用工作流：多步骤流程，面向特定领域
- 工具集成：指导如何处理特定文件格式或 API
- 领域知识：公司特有的知识、数据结构、业务逻辑
- 打包资源：脚本、参考文档与资产，便于重复性工作
Skill 的组成都有哪些
每个 Skill 至少包含一个 SKILL.md，并可附带补充资源：
skill-name/
SKILL.md (必需)
YAML frontmatter 元数据（必需）
name: (必需)
description: (必需)
Markdown 指南（必需）
Bundled Resources (可选)
scripts/ - 可执行脚本（Python/Bash 等）
references/ - 需要时加载到上下文的文档
assets/ - 产出中会用到的文件（模板、图标、字体等）SKILL.md（必需）
元数据质量：frontmatter 中的 name 与 description 决定 Claude 何时调用此 Skill。请具体描述“做什么”“何时用”。使用第三人称措辞，如 “This skill should be used when…”，而非 “Use this skill when…”
打包资源（可选）
Scripts（scripts/）
用于需要确定性或反复被重写的任务。
- 适用情况：相同代码屡次重写，或需要高度可控的执行结果
- 示例：
scripts/rotate_pdf.py - 优势：节省 tokens，可直接执行且确定性强
- 注意：如需环境调整，Claude 仍可能读取脚本
References（references/）
在需要时加载到上下文，为 Claude 提供信息背景。
- 适用情况：有必要让 Claude 查阅的说明文档
- 示例：
references/finance.md（财务结构）、references/api_docs.md（API 规格）等 - 用途：数据库 schema、政策规范、详细流程指导
- 优势：保持
SKILL.md精简，按需加载 - 最佳实践：文档 >10k 字时，可在
SKILL.md提供搜索提示 - 避免重复：详细信息只在一个位置维护，优先放入 reference
Assets（assets/）
不会加载到上下文，但会在输出中直接使用。
- 适用情况：Skill 需要特定文件作为产出的一部分
- 示例：品牌 logo、PPT 模板、前端模板、字体文件等
- 优势：与说明文档分离，Claude 可直接引用
渐进式加载原则
为减少上下文占用，Skill 采用三级加载：
- 元数据（name + description）—— 始终常驻（约 100 词）
SKILL.md正文 —— Skill 被触发时加载（< 5k 词）- 打包资源 —— Claude 视需要调用（理论无限，脚本无需进入上下文即可执行）
Skill 创建流程
请按顺序执行以下步骤，除非有充分理由才能跳过。
第 1 步：通过实例理解 Skill
除非已充分掌握使用场景，否则不要跳过，即便维护既有 Skill 也有价值。
明确 Skill 将解决的具体案例：使用现有流程或与主题专家访谈，收集真实场景、输入输出、成功标准、常见失败、所需数据来源等。若资料仍不足，可要求用户提交更多上下文，让 Claude 扮演抄写员记录要点。
第 2 步：确定 Skill 范围
梳理：
- Skill 的目标与价值
- 覆盖范围（明确边界，避免过宽或过窄）
- 依赖工具 / 数据源
- 权限与安全要求
将范围写成结构化摘要，并与用户或利益相关者确认。
第 3 步：结构化 SKILL.md
推荐结构：
---
name: my-skill
description: Brief third-person summary
---
# Purpose
...
# When to Use
...
# Process
1. ...
2. ...
# Decision Logic
- If ...
- Else ...
# Tool Usage
...
# Inputs Needed
...
# Outputs
...
# Quality Checklist
...撰写注意事项：
- 使用标题、列表与小节明确逻辑
- 保持指令可执行，避免模糊措辞
- 在流程中引用 references / scripts / assets
- 描述成功标准与质量检查点
- 采用第三人称视角，以“Claude”或“该技能”为主语
第 4 步：准备打包资源
- 编写脚本：确保参数化、错误处理、日志清晰
- 整理参考文档：拆分成易查阅的小文件，必要时添加目录或搜索指引
- 准备资产：模板、示例、字体等按用途分类
- 设计文件命名规范，使用小写、短横线分隔
第 5 步：质量检查
检查：
SKILL.md前言包含name与description- 内容结构清晰、语气专业、一致
- 所有引用的文件确实存在
- 资源路径正确、无冗余信息
- 提供质量检查表与常见问题
可以使用 scripts/quick_validate.py 做基础校验。
第 6 步：评测与迭代
建议编写 evaluations/ 场景：
- 正常流程
- 边界情况（缺少信息、异常输入）
- 失败恢复
记录测试结果，更新 Skill。
第 7 步：打包与交付
使用 utils/package_skill.py 将完整目录压缩为 <skill-name>.zip，并附上 README（用途、依赖、安装方法、更新记录）。