claude code skills 到底是什么？

2026-01-14 约 3748 字预计阅读 8 分钟

Claude Code Skills 是 Claude Code（Claude 的编程智能体）的模块化扩展机制，本质上是结构化的指令包，用于教导 Claude 如何处理特定领域的编程任务。它将专业知识、工作流程和执行逻辑封装成可复用的“技能包”，使 Claude 能够像领域专家一样执行任务。

关键特性与设计原则

模型调用（Model-invoked）机制是 Skills 的核心特征。与传统的命令式触发不同，Skills 采用声明式设计，Claude 根据对话内容自动分析用户意图，判断是否需要启用某个 Skill。这种设计减少了用户的认知负担，无需记忆特定命令语法，使交互更加自然流畅。

渐进式披露（Progressive Disclosure） 原则体现在技能执行过程中。根据任务进度逐步注入相关信息，避免一次性信息过载，优化 Token 消耗。例如，在代码审查技能中，Claude 会先分析代码结构，再根据审查进度逐步加载特定检查规则和最佳实践。

标准化操作流程（SOP） 确保输出的一致性和专业性。每个 Skill 将重复性强、专业性高的任务流程标准化，如代码审查、测试编写、API 设计等，确保不同时间、不同用户获得的输出质量保持一致。

定位与边界澄清

与 Slash commands 的区别：Slash commands 需要用户手动输入特定命令触发（如 /review），适合执行重复性任务或脚本；Skills 是自动触发的专业知识库，Claude 根据上下文自动判断何时应用特定技能。

与 CLAUDE.md 的区别：CLAUDE.md 是项目级的全局指令文件，每轮对话都会加载，定义项目的通用规则和偏好；Skills 是针对特定任务的专项能力，只在相关任务出现时激活。

与 MCP（Model Context Protocol）的关系：MCP 侧重于连接外部数据源和工具，提供数据访问能力；Skills 则告诉 Claude 如何利用这些工具和数据执行特定任务，是应用层逻辑的封装。

架构设计与实现原理

分层存储架构

Skills 采用多层存储设计，支持不同范围的共享和优先级覆盖：

存储层级	物理路径示例	适用范围	优先级	典型用途
企业级	企业托管设置路径	组织内所有成员	最高	公司编码规范、安全审查规则
个人级	`~/.claude/skills/`	当前用户的所有项目	次高	个人工作流、常用工具配置
项目级	`.claude/skills/`	当前代码库的所有开发者	中等	项目特定规则、团队约定
插件级	随插件包发布	安装了该插件的用户	最低	第三方工具集成、框架支持

优先级覆盖规则：当同名 Skills 存在于多个层级时，按企业 > 个人 > 项目 > 插件的顺序覆盖。这种设计确保了组织级规范优先于个人偏好，同时允许必要的个性化定制。

技能包结构与组成

每个 Skill 是一个独立的目录，遵循标准化的文件结构：

code-review-skill/
├── SKILL.md                    # 元数据和核心指令（YAML格式）
├── instructions.md             # 详细工作流程和规则
├── resources/                  # 知识库、模板、脚本
│   ├── security-checklist.md   # 安全检查清单
│   ├── performance-guidelines.md # 性能指南
│   └── template-review-report.md # 审查报告模板
└── tools/                      # 外部工具集成定义
    ├── linter-config.json      # 代码检查工具配置
    └── test-coverage-script.sh # 测试覆盖率脚本

执行机制与流程

发现与加载机制：Claude Code 启动时扫描所有配置的 Skills 目录，解析元数据并建立技能索引。扫描过程采用增量策略，只检查修改时间变化的文件。
意图识别与触发检测：基于元数据中的关键词、任务类型描述和上下文模式匹配用户意图。触发检测采用多因素加权算法，考虑关键词匹配度、上下文相关性和历史使用模式。
上下文注入策略：采用动态上下文管理，根据任务阶段逐步加载相关指令。初始阶段只加载核心指令，执行过程中根据需要加载详细规则和资源。
任务执行与工具调用：按照预定义流程执行，可调用外部工具和脚本。执行过程支持中断和恢复，允许用户干预和调整方向。
多技能协作机制：支持技能链式调用，如 CodeReviewSkill 可自动调用 TestSkill 生成测试用例，或调用 DocumentationSkill 更新文档。

使用步骤：从环境配置到技能开发

步骤1：环境准备与基础配置

确认 Claude Code 版本支持 Skills 功能。检查 Claude Code 版本：

claude --version
# 输出示例：Claude Code 1.5.0 (支持Skills)

配置 Skills 存储路径。编辑 Claude Code 配置文件（通常位于 ~/.claude/config.yaml）：

skills:
  # 启用技能功能
  enabled: true
  
  # 技能目录配置（按优先级顺序）
  directories:
    - path: /path/to/enterprise/skills  # 企业级技能
      priority: 100
    - path: ~/.claude/skills            # 个人技能
      priority: 80
    - path: ./.claude/skills            # 项目技能
      priority: 60
    - path: /path/to/plugin/skills      # 插件技能
      priority: 40
  
  # 性能优化配置
  cache:
    enabled: true
    ttl: 3600  # 缓存有效期（秒）
  scan:
    interval: 300  # 目录扫描间隔（秒）
    incremental: true  # 增量扫描

步骤2：创建第一个技能包

创建技能目录结构。以创建代码审查技能为例：

# 在个人技能目录创建新技能
mkdir -p ~/.claude/skills/code-review-skill
cd ~/.claude/skills/code-review-skill

# 创建核心文件
touch SKILL.md instructions.md
mkdir -p resources tools

编写技能元数据文件（SKILL.md）：

---
name: code-review-skill
description: "专业代码审查技能，提供全面的代码质量检查和安全审查"
version: 1.0.0
author: "Your Name"
created: "2024-01-15"
updated: "2024-01-15"

# 触发条件配置
triggers:
  - type: keyword
    patterns:
      - "review this code"
      - "code review"
      - "check the implementation"
      - "审查代码"
    threshold: 0.7  # 匹配阈值
  
  - type: task_type
    patterns:
      - "programming"
      - "code_analysis"
      - "quality_assurance"
  
  - type: file_extension
    patterns:
      - ".py"
      - ".js"
      - ".ts"
      - ".java"
      - ".go"

# 依赖声明
dependencies:
  - tool: 
      name: "pylint"
      version: ">=2.17.0"
      optional: false
  - tool:
      name: "eslint"
      version: ">=8.0.0"
      optional: true
  - library:
      name: "claude-code-tools"
      version: "^1.2.0"

# 权限配置
permissions:
  file_read:
    patterns:
      - "**/*.py"
      - "**/*.js"
      - "**/*.ts"
      - "**/*.java"
    recursive: true
  file_write: false
  command_execute:
    allowed: ["pylint", "eslint", "npm", "pip"]
    restricted: ["rm", "shutdown", "format"]
  network_access: false

# 执行参数
parameters:
  review_depth:
    type: "enum"
    values: ["quick", "standard", "deep"]
    default: "standard"
  include_security:
    type: "boolean"
    default: true
  generate_report:
    type: "boolean"
    default: true

# 性能配置
performance:
  max_context_tokens: 4000
  lazy_load_resources: true
  cache_intermediate: true
---

步骤3：编写详细指令与工作流程

在 instructions.md 中定义技能的具体执行逻辑：

# 代码审查技能 - 详细指令

## 审查流程（标准模式）

### 阶段1：初步分析
1. 识别代码语言和框架
2. 分析代码结构和模块划分
3. 检查基本的语法和格式问题
4. 评估代码复杂度和可维护性

### 阶段2：深度审查
1. **架构设计审查**
   - 检查模块间依赖关系
   - 评估设计模式适用性
   - 验证分层架构合理性

2. **代码质量检查**
   - 圈复杂度不超过15
   - 函数长度不超过50行
   - 类职责单一性检查
   - 重复代码检测

3. **安全审查**（当include_security=true时）
   - SQL注入风险检查
   - XSS漏洞检测
   - 敏感信息硬编码检查
   - 权限验证缺失检查

### 阶段3：工具辅助检查
1. 运行静态代码分析工具
   - Python: pylint, bandit（安全）
   - JavaScript/TypeScript: eslint, sonarjs
   - Java: checkstyle, spotbugs

2. 生成质量指标报告
   - 代码覆盖率（如果测试存在）
   - 技术债务评估
   - 维护性指数

## 输出格式要求

### 审查报告结构

代码审查报告

概览

审查时间: [timestamp]
审查文件: [file list]
总体评分: [A-F]

关键问题（按优先级排序）

[P0] 安全问题: [description]
[P1] 架构问题: [description]
[P2] 代码质量问题: [description]

详细问题列表

安全问题

[文件:行号] [问题描述] [建议修复]

架构问题

[文件:行号] [问题描述] [重构建议]

代码质量问题

[文件:行号] [问题描述] [改进建议]

正面发现

[良好实践1]
[良好实践2]

改进建议总结

短期行动项（本周内）
中期改进项（本季度）
长期优化方向


## 负面示例（避免的模式）

### 不应出现的审查评论
- ❌ "这段代码不好"（过于模糊）
- ❌ "重写整个模块"（缺乏具体指导）
- ❌ "按照我的风格写"（主观偏好）

### 应避免的审查方式
- 不要只关注格式问题而忽略架构缺陷
- 不要提出无法实施的理想化建议
- 不要忽略业务上下文和约束条件

## 具体示例

### 好的审查评论
```python
# 待审查代码
def process_data(data):
    result = []
    for item in data:
        # 复杂的嵌套逻辑
        if item['type'] == 'A':
            if item['value'] > 100:
                result.append(transform_a(item))
        elif item['type'] == 'B':
            # 更多嵌套...
    
# 好的审查建议
建议：考虑使用策略模式替换复杂的if-elif链，提高可扩展性。
示例重构：
class DataProcessor:
    def __init__(self):
        self.strategies = {'A': TransformA(), 'B': TransformB()}
    
    def process(self, data):
        return [self.strategies[item['type']].execute(item) for item in data]

质量检查清单

必须检查项

所有函数都有文档字符串
错误处理完备性
资源释放（文件、连接等）
输入验证和边界检查
日志记录适当性

建议检查项

性能考虑（时间复杂度）
内存使用优化
并发安全性
向后兼容性
配置可调整性


### 步骤4：配置工具与资源

在 `tools/` 目录下创建工具配置文件。例如，创建 Python 代码检查配置：

```json
// tools/pylint-config.json
{
  "extends": "pylint.extensions.mccabe",
  "disable": [
    "missing-docstring",
    "too-few-public-methods",
    "line-too-long"
  ],
  "enable": [
    "refactoring",
    "design",
    "format"
  ],
  "messages": {
    "convention": {
      "max-line-length": 100,
      "max-args": 5,
      "max-locals": 10
    },
    "refactor": {
      "max-complexity": 15,
      "max-branches": 12,
      "max-statements": 50
    }
  },
  "security": {
    "enable": true,
    "checks": [
      "eval-used",
      "exec-used",
      "pickle-usage"
    ]
  }
}

在 resources/ 目录下添加检查清单和模板：

# resources/security-checklist.md

## 认证与授权
- [ ] 密码存储使用加盐哈希
- [ ] 会话令牌安全生成和验证
- [ ] 权限检查在服务端执行
- [ ] 最小权限原则应用

## 输入验证
- [ ] 所有用户输入都经过验证
- [ ] 使用白名单而非黑名单
- [ ] 文件上传类型和大小限制
- [ ] SQL参数化查询

## 数据保护
- [ ] 敏感数据加密存储
- [ ] 日志中不记录敏感信息
- [ ] 数据传输使用TLS
- [ ] 密钥管理安全

步骤5：测试与验证技能

创建测试用例验证技能功能：

# 创建测试项目
mkdir -p /tmp/test-project
cd /tmp/test-project

# 创建测试代码文件
cat > test_code.py << 'EOF'
def insecure_function(user_input):
    # 安全漏洞示例：SQL注入
    query = f"SELECT * FROM users WHERE name = '{user_input}'"
    return execute_query(query)

def complex_function(x):
    # 代码质量问题：圈复杂度过高
    if x > 0:
        if x < 10:
            for i in range(x):
                if i % 2 == 0:
                    print("even")
                else:
                    print("odd")
        elif x < 20:
            return x * 2
    elif x < 0:
        return -x
    else:
        return 0
EOF

# 通过Claude Code测试技能
claude code --skill-test code-review-skill test_code.py

验证技能输出是否符合预期。检查：

是否正确识别了安全问题（SQL注入）
是否检测到代码质量问题（高圈复杂度）
报告格式是否符合要求
建议是否具体可行

步骤6：部署与共享技能

将技能打包供团队使用：

# 创建技能包
cd ~/.claude/skills/code-review-skill

# 创建部署清单
cat > deploy.yaml << 'EOF'
name: code-review-skill
version: 1.0.0
dependencies:
  - pylint>=2.17.0
  - bandit>=1.7.0
install_script: |
  pip install pylint bandit
  mkdir -p ~/.claude/skills
  cp -r . ~/.claude/skills/code-review-skill
EOF

# 验证技能包完整性
claude skill validate code-review-skill

关键实现细节与最佳实践

元数据设计模式

有效的 Skills 元数据应包含以下关键元素：

# 触发条件优化设计
triggers:
  # 多模式组合触发，提高准确性
  - type: composite
    conditions:
      - type: keyword
        patterns: ["refactor", "improve", "optimize"]
        weight: 0.3
      - type: code_pattern
        patterns: ["long_method", "deep_nesting", "high_complexity"]
        weight: 0.4
      - type: context
        patterns: ["after_implementation", "during_maintenance"]
        weight: 0.3
    threshold: 0.6  # 综合阈值

指令设计最佳实践

具体化而非抽象化：使用具体代码示例代替抽象描述
包含负面约束：明确说明要避免的模式和反模式
分阶段执行：复杂任务分解为可管理的阶段
工具版本锁定：指定依赖工具的具体版本，确保环境一致性

性能优化策略

# 性能优化配置示例
performance:
  # 上下文管理
  max_context_tokens: 4000
  compression: true
  summarize_large_outputs: true
  
  # 缓存策略
  cache:
    enabled: true
    strategy: "lru"
    max_size: 100
    ttl: 3600
    
  # 懒加载配置
  lazy_load:
    resources: true
    tools: true
    instructions: false  # 核心指令立即加载
    
  # 并行处理
  parallel:
    enabled: true
    max_workers: 3
    timeout: 30

目录