skill-creator

技能创建器

此技能提供创建有效技能的指导。

关于技能

技能是模块化、独立的软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备程序性知识的专业 Agent，而这些知识是任何模型都无法完全掌握的。

技能提供的内容

1. 专业工作流 - 特定领域的多步骤流程
2. 工具集成 - 使用特定文件格式或 API 的说明
3. 领域专业知识 - 公司专属知识、架构和业务逻辑
4. 捆绑资源 - 用于复杂且重复性任务的脚本、参考资料和资源文件

技能的组成

每项技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据质量： YAML frontmatter 中的 name 和 description 决定 Claude 何时使用该技能。请明确说明技能的功能和适用场景。使用第三人称（例如，“This skill should be used when...”而不是“Use this skill when...”）。

捆绑资源（可选）

脚本（scripts/）

用于需要确定性可靠性的任务或需要反复重写的代码（Python/Bash 等）。

• 何时包含：当相同的代码需要反复重写，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省令牌、结果确定，且可以在不加载到上下文中的情况下执行
• 注意：Claude 可能仍需读取脚本，以便进行修补或针对特定环境进行调整

参考资料（references/）

按需加载到上下文中的文档和参考材料，用于指导 Claude 的流程和思考。

• 何时包含：当 Claude 工作时需要查阅文档时
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，仅在 Claude 判断有需要时加载
• 最佳实践：如果文件较大（>10k words），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考文件中，而不是两者都有。除非详细信息确实是技能的核心内容，否则优先放在参考文件中——这样能让 SKILL.md 保持精简，同时确保信息易于查找，不会占用过多上下文窗口。SKILL.md 中仅保留必要的流程指令和工作流指导；将详细的参考材料、架构和示例移至参考文件。

资源文件（assets/）

不用于加载到上下文中，而是供 Claude 在生成的输出中使用的文件。

• 何时包含：当技能需要使用将在最终输出中出现的文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板代码 assets/frontend-template/、字体排印用的 assets/font.ttf
• 使用场景：模板、图像、图标、样板代码、字体、需要复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Claude 无需加载文件即可使用它们

隐私和路径引用

重要：面向公众发布的技能不得包含特定于用户或公司的信息：

• 禁止：用户目录的绝对路径（/home/username/、/Users/username/、/mnt/c/Users/username/）
• 禁止：个人用户名、公司名称、部门名称、产品名称
• 禁止：OneDrive 路径、云存储路径或任何特定于环境的绝对路径
• 禁止：硬编码的技能安装路径，例如 ~/.claude/skills/ 或 /Users/username/Workspace/claude-code-skills/
• 允许：技能包内的相对路径（scripts/example.py、references/guide.md）
• 允许：标准占位符（~/workspace/project、username、your-company）
• 最佳实践：使用简单的相对路径引用随附脚本，例如 scripts/script_name.py——Claude 会解析实际位置

版本管理

重要：技能不应在 SKILL.md 中包含版本历史或版本号：

• 禁止：在 SKILL.md 中添加版本部分（## Version、## Changelog、## Release History）
• 禁止：在 SKILL.md 正文内容和前置元数据中添加版本号（也不要放置 version: 键）
• 正确位置：版本由分发物一侧统一管理（在此仓库中为 .claude-plugin/plugin.json 的 version）
• 原因：市场基础设施负责版本管理；SKILL.md 应是专注于功能的恒久内容
• 示例：不要在 SKILL.md 中记录 v1.0.0 → v1.1.0 的变更，只需更新插件版本

渐进式披露设计原则

技能采用三级加载系统，以高效管理上下文：

1. 元数据（名称 + 描述） - 始终处于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个词）
3. 随附资源 - Claude 按需加载（无限*）

*之所以无限，是因为脚本可以执行，而无需读入上下文窗口。

创建技能的最佳实践

Anthropic 已撰写技能编写最佳实践；创建或更新任何技能之前，你 SHOULD 获取并阅读该文档，链接为 https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md

⚠️ 重要：在源位置编辑技能

切勿在 ~/.claude/plugins/cache/ 中编辑技能——那是只读缓存目录。在那里进行的所有更改都会：

• 在缓存刷新时丢失
• 不会同步到源代码管理
• 白费功夫，之后还需要手动合并

务必确认你正在编辑源仓库：

# WRONG - cache location (read-only copy)
~/.claude/plugins/cache/<your-marketplace>/my-skill/1.0.0/my-skill/SKILL.md

# RIGHT - source repository
/path/to/your/claude-code-skills/my-skill/SKILL.md

进行任何编辑之前，请确认文件路径不包含 /cache/ 或 /plugins/cache/。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”；只有在有明确理由表明某个步骤不适用时，才跳过该步骤。

步骤 1：通过具体示例了解技能

只有在已充分了解该技能的使用模式时，才跳过此步骤。即使是在处理现有技能时，这一步仍然很有价值。

要创建有效的技能，必须清楚了解该技能的具体使用方式。这种了解可以来自用户提供的直接示例，也可以来自经过用户反馈验证的生成示例。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应该支持哪些功能？编辑、旋转，还有其他功能吗？”
• “你能举一些这个技能的使用示例吗？”
• “我能想到用户可能会提出这样的请求：‘去掉这张图片中的红眼’或‘旋转这张图片’。你还能想到其他用法吗？”
• “用户说什么时应该触发这个技能？”

为避免让用户应接不暇，不要在一条消息中提出过多问题。先问最重要的问题，再根据需要继续追问，以提升效果。

当明确了解该技能应支持的功能后，即可结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请通过以下方式分析每个示例：

1. 考虑如何从头开始完成示例中的任务
2. 确定应给予 Claude 多大的自由度
3. 找出在重复执行这些工作流时，有哪些脚本、参考资料和资源会有所帮助

让具体程度与任务风险相匹配：

• 高自由度（文本指令）：存在多种有效方法；最佳路径取决于上下文（例如，代码审查、故障排查、内容分析）
• 中等自由度（带参数的伪代码）：存在首选模式，同时允许适度变化（例如，API 集成模式、数据处理工作流）
• 低自由度（精确脚本）：操作容易出错、一致性至关重要、执行顺序很重要（例如，PDF 旋转、数据库迁移、表单验证）

例如，在构建用于处理“帮我旋转这个 PDF”等请求的 pdf-editor 技能时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会有所帮助

例如，在设计用于处理“帮我构建一个待办事项应用”或“帮我构建一个追踪步数的仪表板”等请求的 frontend-webapp-builder 技能时，分析表明：

1. 每次编写前端 Web 应用都需要重复编写相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会有所帮助

例如，在构建用于处理“今天有多少用户登录了？”等请求的 big-query 技能时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表结构及其关系
2. 将记录表结构的 references/schema.md 文件存放在技能中会有所帮助

要确定技能包含哪些内容，请分析每个具体示例，并列出要纳入的可复用资源：脚本、参考资料和资源。

步骤 3：初始化技能

此时，就可以实际创建技能了。

仅当正在开发的技能已经存在，且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头开始创建新技能时，务必运行 init_skill.py 脚本。该脚本可便捷地生成新的技能模板目录，自动包含技能所需的一切，从而让技能创建过程更加高效可靠。

用法：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成包含适当 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，根据需要自定义或删除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

编辑（新生成或已有的）技能时，请记住，该技能是为另一个 Claude 实例创建的。重点纳入对 Claude 有用且不显而易见的信息。考虑哪些流程知识、领域专属细节或可复用资源，能够帮助另一个 Claude 实例更有效地完成这些任务。

从可复用技能内容入手

开始实施时，先使用上文确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实施 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，以存放在 assets/ 中，或提供文档，以存放在 references/ 中。

此外，删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件以展示结构，但大多数技能并不需要这些文件。

更新现有技能时：扫描所有现有参考文件，检查是否需要相应更新。新功能通常需要更新架构、工作流或其他现有文档，以保持一致性。

参考文件命名

文件名必须清晰易懂，无需阅读文件内容。

格式：<content-type>_<specificity>.md

示例：

• ❌ commands.md、cli_usage.md、reference.md
• ✅ script_parameters.md、api_endpoints.md、database_schema.md

测试：仅凭文件名，是否就能了解文件内容？

更新 SKILL.md

写作风格： 整个技能都使用祈使／不定式形式（以动词开头的指令），不要使用第二人称。使用客观、指导性的语言（例如，“要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可以使内容对 AI 更一致、更清晰。

完成 SKILL.md 时，请回答以下问题：

1. 技能的用途是什么？请用几句话说明。
2. 何时应使用该技能？
3. 在实际使用中，Claude 应如何使用该技能？请引用上文编写的所有可复用技能内容，让 Claude 知道如何使用它们。

第 5 步：清理审查（可选）

执行此步骤前先询问用户：“此技能似乎摘自商业项目。你是否希望我执行清理审查，在公开发布前移除特定于业务的内容？”

以下情况可跳过此步骤：

• 技能是从头开始为公开用途创建的
• 用户明确拒绝清理
• 技能仅供内部／私人使用

执行清理的情况：

• 技能摘自商业／内部项目
• 技能包含真实系统中的领域特定示例
• 技能将公开分发或提供给其他团队

清理流程：

1. 加载检查清单：阅读 references/sanitization_checklist.md，了解详细指导

2. 运行自动扫描，识别可能的敏感内容：

   # Product/project names, person names, paths
   grep -rniE "<product-name>|<codename>|<team-name>|/Users/|/home/" skill-folder/
   
   # Chinese characters (if skill should be English-only)
   grep -rn '[一-龥]' skill-folder/
   

3. 检查并替换以下各类内容：

   • 产品／项目名称 → 通用术语
   • 人名 → “Alice”、“Bob”或基于角色的称谓
   • 实体名称 → 通用实体（ORDER、USER、PRODUCT）
   • 文件夹结构 → 通用路径
   • 内部行话 → 行业标准术语
   • 特定语言内容 → 翻译或删除

4. 验证完整性：

   • 重新运行所有 grep 模式（应无匹配结果）
   • 通读技能内容，确保连贯
   • 确认技能仍能正常运行

常见替换：

特定于业务的内容	通用替换
“Project Nimbus”（社内代码名）	“the project”
“Acme Reviewer Portal”（产品名称）	“the application”
“Alice will handle...” （真实人名）	基于角色的称谓（“the reviewer will handle...”）
REVIEW_RESULT（内部架构名称）	ORDER
内部行话（“ultrathink”）	“deep review”
混入的其他语言注释	翻译为正文语言或删除

第 6 步：安全审查

在打包或分发技能之前，运行安全扫描器，检测硬编码机密和个人信息：

# Required before packaging
python scripts/security_scan.py <path/to/skill-folder>

# Verbose mode includes additional checks for paths, emails, and code patterns
python scripts/security_scan.py <path/to/skill-folder> --verbose

检测范围：

• 通过 gitleaks 检测硬编码机密（API 密钥、密码、令牌）
• 在详细模式下检测个人信息（用户名、电子邮件、公司名称）
• 在详细模式下检测不安全的代码模式（命令注入风险）

首次设置： 如果尚未安装 gitleaks，请安装：

# macOS
brew install gitleaks

# Linux/Windows - see script output for installation instructions

退出代码：

• 0 - 无问题（可安全打包）
• 1 - 高严重性问题
• 2 - 严重问题（分发前必须修复）
• 3 - 未安装 gitleaks
• 4 - 扫描错误

修复检测到的机密：

1. 从所有文件中移除硬编码机密
2. 使用环境变量：os.environ.get("API_KEY")
3. 如果凭据之前已提交到 git，请轮换凭据
4. 重新运行扫描，在打包前确认问题已修复

第 7 步：打包技能

技能准备就绪后，应将其打包为可分发的 zip 文件并分享给用户。打包流程会先自动验证技能，确保其满足所有要求：

scripts/package_skill.py <path/to/skill-folder>

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 路径引用完整性 - SKILL.md 中提及的所有 scripts/、references/ 和 assets/ 路径都必须存在

2. 如果验证通过，则打包技能，创建以技能命名的 zip 文件（例如 my-skill.zip），其中包含所有文件，并保留适用于分发的正确目录结构。

常见验证失败： 如果 SKILL.md 引用了 scripts/my_script.py，但该文件不存在，验证将失败并显示“缺少引用的文件：scripts/my_script.py”。请确保所有打包的资源都存在，然后再进行打包。

如果验证失败，脚本会报告错误并退出，不会创建软件包。修复所有验证错误后，再次运行打包命令。

第 8 步：更新分发元数据

此仓库的 marketplace 采用 single-plugin 架构（.claude-plugin/marketplace.json 仅包含 plugin 列表，不包含按技能划分的条目）。添加或更新技能后：

1. 更新技能数量说明：将 README.md 和 docs/adoption.md 中的“skills N 个”更新为实际数量
2. 提升 plugin 版本：按照 semver 规则提升 .claude-plugin/plugin.json 中的 version
   • Patch（0.1.x）：错误修复、拼写更正
   • Minor（0.x.0）：新技能、新功能、新增参考资料
   • Major（x.0.0）：不兼容变更、工作流重构
3. 运行 lint：uv run python scripts/lint_skills.py --dir skills（frontmatter 架构验证）

不得向 .claude-plugin/marketplace.json 添加按技能划分的 version/category/keywords/skills[]（这不符合此 kit 的架构）。

第 9 步：迭代

测试技能后，用户可能会要求改进。通常，这会在用户使用技能后立即发生，此时他们对技能表现仍有新鲜的印象。

迭代流程：

1. 在实际任务中使用技能
2. 注意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或打包资源
4. 实施更改并再次测试

改进原则： 只添加能解决已观察到问题的内容。如果最佳实践已经涵盖，就不要重复添加。