跳到主要内容

Claude Skills 系统完全指南

概述​

Skills 是 Claude Code 的革命性功能，提供渐进式披露上下文的模块化知识包。它们就像是专门化的入职文档，能够训练 AI 完全按照你的团队方式工作。

Skills 的核心价值​

解决根本矛盾​

Skills 通过分层信息披露机制解决全面知识与有限上下文之间的矛盾：

  • 轻量级索引：Claude 始终只看到技能名称和描述（约 100 词）
  • 按需加载：只有当相关任务出现时才加载详细指令
  • 引用扩展：详细文档仅在执行过程中按需加载

与 CLAUDE.md 的对比​

特性SkillsCLAUDE.md
触发方式按需自动加载始终加载
适用范围跨项目、跨平台项目特定
内容结构分模块、支持引用单一文件
上下文管理渐进式披露全量加载
可执行代码✅ 支持❌ 不支持

创建 Skills 的完整流程​

五步创建法​

第1步：理解核心需求​

在编写之前明确：

  • 具体任务：技能完成什么操作？
  • 触发条件：何时激活？
  • 成功标准：什么算成功？
  • 边界情况：有哪些限制？

第2步：编写技能名称​

规范：

  • 使用小写和连字符：pdf-editor、brand-guidelines
  • 简短明确，便于识别
  • 具有描述性

第3步：编写描述字段​

描述是最关键的组件，决定技能何时激活：

弱描述示例：

This skill helps with PDFs and documents.

强描述示例：

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. Use for document workflows and batch operations. Not for simple PDF viewing or basic conversions.

第4步：编写主要指令​

指令应：

  • 结构化、可扫描、可操作
  • 使用 markdown 标题和项目符号
  • 按阶段组织工作流程
  • 包含具体示例

第5步：测试和验证​

系统性测试：

  • 正常操作场景
  • 边界情况处理
  • 超出范围的响应

Skills 结构详解​

完整目录结构​

your-skill/
├── SKILL.md              # 核心指令文件
├── references/           # 详细引用文档
│   ├── finance.md       # 财务相关
│   ├── product.md       # 产品使用
│   └── sales.md         # 销售相关
└── assets/              # 可执行资源
    ├── scripts/         # 脚本文件
    ├── templates/       # 模板文件
    └── examples/        # 示例文件

SKILL.md 核心文件​

YAML 前置数据​

---
name: sql-analysis
description: Use when analyzing business data: revenue, ARR, customer segments, product usage, or sales pipeline. Provides table schemas, metric definitions, required filters, and query patterns specific to ACME's data warehouse.
license: Proprietary. LICENSE.txt has complete terms
---

Markdown 指令结构​

# SQL Analysis Skill

## Quick Start Workflow
When a user asks for data analysis:
1. **Clarify the request**
   - What time period? (default to current year)
   - Which customer segment?
   - What business decision will this inform?

2. **Check for existing dashboards**
   - Look in `references/dashboards.md`
   - If exists, direct them there first

## Knowledge Base
For detailed table schemas:
- **Revenue & Finance** → `references/finance.md`
- **Product Usage** → `references/product.md`
- **Sales & Pipeline** → `references/sales.md`

References 目录​

包含按需加载的详细文档：

references/finance.md 内容：

  • 表结构：列名、数据类型、描述
  • 标准过滤器：应始终应用的 WHERE 子句
  • 指标定义：ARR、运行率等计算公式
  • 常见查询模式：SQL 代码片段
  • 边界情况：已知特殊性

实际应用示例​

示例1：财务数据技能​

---
name: financial-analysis
description: Use when analyzing business financial data: revenue, expenses, profit margins, cash flow, or financial forecasting. Provides standard financial metrics, GAAP compliance rules, and visualization templates specifically for corporate financial reporting.
---

示例2：品牌指南技能​

---
name: brand-guidelines
description: Applies our company's official brand colors and typography to any artifact. Use when brand colors, style guidelines, visual formatting, or company design standards apply to documents, presentations, or web content.
---

示例3：代码审查技能​

---
name: code-review
description: Perform comprehensive code reviews focusing on security vulnerabilities, performance bottlenecks, maintainability issues, and adherence to team coding standards. Use for pull request reviews, legacy code assessment, or architectural decision validation.
---

最佳实践​

1. 从用例出发​

  • 不要凭空创建技能
  • 遇到重复任务时才构建
  • 问自己：是否做过5次？未来还会做10次？

2. 定义成功标准​

告诉 Claude 什么样的输出算是好的：

  • 创建财务报告时，指定需要的部分、格式标准
  • 在指令中包含标准，让 Claude 自我检查

3. 使用 skill-creator 技能​

claude plugin install claude-skill-creator

skill-creator 技能帮助：

  • 提出澄清问题
  • 建议描述改进
  • 帮助正确格式化指令

4. 渐进式披露​

使用"菜单"方法：

  • SKILL.md 描述可用内容
  • 使用相对路径引用各选项
  • Claude 只选择相关文件

技能测试与验证​

测试矩阵​

正常操作测试​

  • 测试常见请求
  • 验证预期输出
  • 确认一致性

边界情况测试​

  • 数据缺失时的处理
  • 异常格式的响应
  • 模糊指令的处理

超出范围测试​

  • 相关但不匹配的任务
  • 确认技能保持休眠
  • 让其他技能处理

功能测试​

# 测试用例示例

## 测试场景1：正常财务分析
输入："分析Q3收入趋势"
预期：激活技能，提供准确分析

## 测试场景2：边界情况
输入："分析不完整数据"
预期：优雅处理，指出缺失

## 测试场景3：超出范围
输入："写一首诗"
预期：不激活财务技能

团队协作​

分享方式​

1. ZIP 文件分享​

  • 快速非正式协作
  • 适合小团队

2. Git 仓库​

git clone https://github.com/company/skills-repo
cp -r skills/* ~/.claude/skills/

3. 插件包​

  • 便于团队分发
  • 需要插件开发知识

组织级治理​

小团队​

  • 维护共享技能规范库
  • 包含使用示例和故障排除

大型团队​

  • 指定技能所有者（财务、法务等）
  • 中心化的技能 wiki
  • 定期审查和更新

高级技巧​

1. 技能组合​

设计可相互调用的技能：

## 相关技能
- `financial-reporting` - 生成报告
- `data-visualization` - 创建图表

2. 动态内容​

使用模板系统：

## 模板
使用 {{company_name}} 替代公司名
使用 {{time_period}} 替代时间范围

3. 版本管理​

在 SKILL.md 中包含版本信息：

---
version: 2.1.0
last_updated: 2025-01-15
changelog:
  - "2.1.0: Added support for new data source"
  - "2.0.0: Complete refactor of query patterns"
---

常见问题​

Q: 技能不被激活？​

检查描述是否：

  • 包含具体的触发场景
  • 使用了明确的动词
  • 涵盖了预期的上下文

Q: 技能输出不一致？​

确保：

  • 指令清晰无歧义
  • 包含具体的示例
  • 定义了成功标准

Q: 上下文窗口不够？​

使用：

  • 渐进式披露
  • 引用文件
  • 条件加载

示例技能模板​

通用模板​

---
name: your-skill-name
description: [详细的100词描述，包含何时使用、能做什么、不适用场景]
---

# 技能名称

## 快速开始
[3-5步的简单工作流程]

## 工作流程
[详细的分步说明]

## 参考资料
- [主题1] → `references/topic1.md`
- [主题2] → `references/topic2.md`

## 限制
[明确说明不能做什么]

总结​

Skills 让你能够：

  • 构建持久化的组织知识
  • 跨项目复用专业知识
  • 实现渐进式信息披露
  • 创建可组合的工作流

通过合理使用 Skills，你可以将 Claude Code 转变为理解你业务逻辑的专业助手。

相关资源​