Claude Code 技能系统详细指南

Claude Code 技能系统详细指南

基于对 GitHub 仓库 的分析，为您整理了 Claude Code 技能系统的完整说明。

1.1 技能系统概述

1.1.1 什么是技能？

技能是包含指令、脚本和资源的文件夹，Claude 可以动态加载这些内容以在特定任务上表现更好。技能本质上是为 Claude 提供的「入职指南」，将通用的 AI 助手转变为具备专业领域知识和工作流程的专门助手。

1.1.2 技能的用途

  • 专业工作流程 - 为特定领域提供多步骤程序化指导
  • 工具集成 - 教会 Claude 如何使用特定的文件格式或 API
  • 领域专业知识 - 提供公司特定的知识、架构和业务逻辑
  • 资源打包 - 为复杂重复性任务提供脚本、参考资料和资产

1.2 技能的核心结构

1.2.1 基本技能结构

技能名称/
├── SKILL.md (必需)
├── scripts/ (可选)
├── references/ (可选)
└── assets/ (可选)

1.2.2 文件说明

1.2.2.1 SKILL.md (必需文件)

技能的入口点，包含 YAML 前置数据和 Markdown 说明：

---
name: 技能名称 (小写，用连字符分隔)
description: 详细描述技能功能和使用时机
license: 许可证 (可选)
allowed-tools: 预批准工具列表 (可选)
metadata: 额外的键值对 (可选)
---

具体的技能说明正文和使用指令工作流程

1.2.2.2 scripts/ 目录 (可选)

可执行代码文件（Python、Bash 等）：

  • 用途：需要确定性可靠性的任务或重复编写的代码
  • 示例：rotate_pdf.py 用于 PDF 旋转
  • 优势：令牌高效、确定性、可以不加载到上下文就执行

1.2.2.3 references/ 目录 (可选)

文档和参考资料：

  • 用途：Claude 在执行过程中需要参考的文档
  • 示例：数据库架构、API 文档、公司政策
  • 最佳实践：保持 SKILL.md 精简，仅在需要时加载

1.2.2.4 assets/ 目录 (可选)

输出中使用的文件：

  • 用途：将在 Claude 输出中使用的文件
  • 示例：模板、图标、样例代码、字体
  • 优势：将输出资源与文档分离

1.3 创建自定义技能的步骤

1.3.1 第一步：理解技能需求

通过具体示例明确技能功能：

  • 技能应支持哪些功能？
  • 用户会如何使用这个技能？
  • 什么情况下应该触发这个技能？

1.3.2 第二步：规划可重用内容

分析示例并确定需要的资源：

  • 识别重复编写的代码 → scripts/
  • 确定需要的参考资料 → references/
  • 确定输出模板和资源 → assets/

1.3.3 第三步：初始化技能结构

使用模板创建技能框架：

scripts/init_skill.py <技能名称> --path <输出目录>

1.3.4 第四步：编写技能内容

1.3.4.1 YAML 前置数据编写要点

---
name: pdf-editor
description: 全面的 PDF 操作工具包，用于提取文本和表格、创建新 PDF、合并/拆分文档以及处理表单。当 Claude 需要填写 PDF 表单或大规模编程处理、生成或分析 PDF 文档时使用。
---

描述编写技巧：

  • 说明技能功能
  • 明确使用时机和触发条件
  • 包含所有「何时使用」的信息

1.3.4.2 正文内容编写要点

  • 使用祈使/不定式形式
  • 保持简洁（低于 500 行，5k 词以内）
  • 提供具体示例和使用指南

1.3.5 第五步：打包技能

scripts/package_skill.py <技能文件夹路径>

打包过程会：

  1. 验证技能格式和内容
  2. 创建可分发的 .skill 文件

1.3.6 第六步：迭代优化

基于实际使用反馈改进技能。

1.4 安装和使用技能

1.4.1 Claude Code 中的安装

1.4.1.1 方法一：通过市场安装

/plugin marketplace add anthropics/skills

然后选择要安装的技能包。

1.4.1.2 方法二：直接安装

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

1.4.2 使用技能

安装后，直接提及技能名称即可：

使用 PDF 技能从 path/to/file.pdf 中提取表单字段

1.5 技能示例和最佳实践

1.5.1 示例技能类型

1.5.1.1 创意和设计类

  • algorithmic-art - 使用 p5.js 创建生成艺术
  • canvas-design - 设计.png 和.pdf 格式的视觉艺术
  • slack-gif-creator - 创建优化的 Slack GIF 动图

1.5.1.2 开发和技术类

  • mcp-builder - 创建 MCP 服务器
  • webapp-testing - 使用 Playwright 测试 Web 应用
  • document-skills - 处理各种文档格式

1.5.1.3 企业和通信类

  • brand-guidelines - 应用品牌视觉规范
  • internal-comms - 撰写内部通信文档
  • theme-factory - 风格化和主题化

1.5.2 最佳实践

1.5.2.1 渐进式披露设计

  • 元数据（名称 + 描述） - 始终在上下文中（约 100 词）
  • SKILL.md 正文 - 技能触发时加载（<5k 词）
  • 打包资源 - 按需加载（无限制）

1.5.2.2 内容组织模式

  • 高级指南 + 参考资料：在 SKILL.md 中保留核心，详细信息移至参考文件
  • 领域特定组织：按领域或框架分离内容
  • 条件性细节：基础内容 + 高级内容链接

1.5.2.3 令牌效率

  • 简洁是关键：挑战每条信息：“Claude 真的需要这个解释吗？”
  • 避免冗余：信息应在 SKILL.md 或参考文件中，不要重复
  • 合理限制自由度：根据任务的脆弱性和可变性匹配具体程度

1.6 技能与 Claude Code 的集成

1.6.1 集成方式

  1. 市场系统 - 通过官方技能市场发现和安装
  2. 本地技能 - 直接加载本地技能目录
  3. 动态加载 - 根据上下文自动触发相关技能

1.6.2 技能触发机制

Claude 通过分析 SKILL.md 中的 description 字段来确定何时使用特定技能。因此，描述必须：

  • 清晰说明技能功能
  • 明确使用时机和触发条件
  • 包含足够的关键词

1.6.3 技能生态系统

  • 官方技能 - Anthropic 提供的示例和文档技能
  • 合作伙伴技能 - 第三方开发的集成技能
  • 自定义技能 - 用户或组织开发的专业技能

1.7 高级技巧和建议

1.7.1 技能设计原则

  1. 专注核心功能 - 每个技能解决特定问题
  2. 模块化设计 - 便于组合和重用
  3. 向后兼容 - 考虑版本升级路径
  4. 错误处理 - 提供故障排除指导

1.7.2 技能维护

  • 定期更新依赖库和工具
  • 收集用户反馈并持续改进
  • 监控技能性能和效果
  • 保持文档的及时性

1.7.3 安全考虑

  • 验证输入数据和参数
  • 实施适当的权限控制
  • 避免在技能中硬编码敏感信息
  • 定期安全审计

通过这个技能系统，您可以显著扩展 Claude Code 的能力，使其能够更好地处理特定的工作流程和专业任务。无论是处理特定文件格式、集成第三方 API，还是实施公司特定的工作流程，技能系统都提供了一个强大而灵活的框架。