Claude Code Skills 深度研究报告

研究概览

研究主题：Claude Code Skills 功能深度分析与最佳实践

Claude Code Skills 是 Anthropic 于 2025 年推出的革命性功能，并于 2025 年 12 月 18 日正式发布为开放标准（Agent Skills）。Skills 是一种模块化、自包含的"专业技能包"，能够将 Claude 从通用型 AI 助手转变为具备特定领域专业知识的专家型 Agent。

核心发现

1. 什么是 Skills？

1.1 定义

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as 'onboarding guides' for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

翻译为：Skills 是一种模块化、自包含的"专业技能包"，通过提供专业领域知识、工作流程和工具来扩展 Claude 的能力。它就像是特定领域或任务的"入职指南"，将 Claude 从通用型 Agent 转变为具备程序性知识的专业型 Agent。

1.2 核心价值

Skills 能够提供：

• 专业工作流程：多步骤的作业程序（如 Code Review、PR 处理）
• 工具整合：与特定文件格式或 API 的交互方法
• 领域专业知识：公司或团队特有的商业逻辑和惯例
• 资源：脚本、参考文件、模板等执行任务时需要的素材

1.3 与 CLAUDE.md 的区别

2. 核心架构：渐进式披露

2.1 设计理念

渐进式披露（Progressive Disclosure） 是 Skills 最核心的设计创新。这个概念类似于 Google Maps 导航：不会一次性显示所有细节，而是根据需要逐步提供信息。

2.2 三层加载架构

2.3 核心优势

• 理论上无限的知识容量：由于按需加载，可以在一个 Skill 中打包大量知识
• 高效的上下文管理：只需 50-100 tokens 预载元数据，完整内容约 500 tokens
• 性能可预测：即使拥有数百个 Skills 也不会影响启动性能

3. 文件结构与规范

3.1 最小结构

skill-name/
└── SKILL.md   # 必需

3.2 标准完整结构

skill-name/
├── SKILL.md              # 必需：核心指令文件
├── scripts/              # 可选：可执行代码（Python、Bash、JavaScript）
├── references/           # 可选：参考文档
└── assets/               # 可选：静态资源（模板、图片、数据文件）

3.3 YAML Frontmatter（必需）

---
name: skill-name
description: A description of what this skill does and when to use it.
---

字段规则

• name 字段：长度 1-64 个字符；只能使用小写字母、数字和 -；必须与目录名称一致
• description 字段：长度 1-1024 个字符；应描述 Skill 做什么、何时使用；是决定 Skill 何时被触发的关键

4. 与其他机制对比

4.1 四大扩展机制

4.2 Skills vs MCP

这是两个解决不同层次问题的机制：

5. Agent Skills 开放标准

5.1 标准资源

• 规范网站：https://agentskills.io
• GitHub：https://github.com/agentskills/agentskills
• 规范文档：https://agentskills.io/specification

5.2 支持平台

Agent Skills 标准已被多家主流平台采用：

5.3 核心规范

规范总计 不足 1000 词，定义了：

1. 文件结构：SKILL.md + 可选目录（scripts/、references/、assets/）
2. YAML Frontmatter：name 和 description 字段规则
3. 渐进式披露：三层加载机制
4. 目录命名：必须与 name 字段一致

6. 官方技能库生态

6.1 Anthropic 官方技能库

• GitHub 仓库：https://github.com/anthropics/skills
• Star 数：约 29k-39.4k ⭐
• 创建时间：约 5 个月前
• 维护状态：持续活跃

6.2 官方技能分类

6.3 社区技能库

6.4 技能市场

• SkillsMP：全球最大技能市场，超过 60,000 个技能
• ClawHub：OpenClaw 技能商店，提供 1715+ 技能

7. 最佳实践

7.1 Description 撰写技巧

Description 是 Skill 最重要的部分，决定了 Agent 是否能正确触发。

description: Helps with PDFs.

description: Extracts text and tables from PDF files, fills PDF forms,
and merges multiple PDFs. Use when working with PDF documents or when
the user mentions PDFs, forms, or document extraction.

关键原则

1. 明确列出能做什么
2. 说明何时该被触发
3. 包含用户可能说的关键词
4. 写成给工程师看的技术说明，不是营销文案

7.2 善用 Progressive Disclosure

code-review-skill/
├── SKILL.md                      # 核心指令，500 行以内
├── references/
│   ├── security-checklist.md     # 安全检查清单
│   ├── performance-patterns.md   # 性能模式
│   └── style-guide.md            # 代码风格指南
└── scripts/
    └── lint-check.sh             # 检查脚本

7.3 Scripts 最佳实践

1. 运行前做输入校验
2. 最小权限原则（workspace-only、deny-by-default）
3. 将脚本视为供应链依赖：需要签名、审计、锁版本
4. 在 Skill 中固化验证步骤

8. 安全注意事项

8.1 五层防御体系

8.2 供应链威胁

"2026 年代表了 AI 代理生态系统中围绕 Skills 规范的首次重大供应链威胁，这不会是最后一次。"
— Snyk 报告（2026）

8.3 黄金法则

9. OpenClaw Skills 机制

9.1 OpenClaw 简介

• 标语："The AI that actually does things"
• 核心语言：TypeScript
• 部署：阿里云或本地服务器

"Agent 强不强，模型能力虽然很重要，但关键在 Skills。模型只是大脑，Skills 才是手、是工具、是执行力。"

9.2 OpenClaw Skills 特点

1. 多目录加载与覆盖优先级：bundled → ~/.openclaw/skills → <workspace>/skills
2. Load-time Gating：读取 metadata.openclaw.requires 决定 Skill 是否 eligible
3. Prompt 注入策略：将"可用技能清单"以紧凑 XML 形式注入系统提示
4. Slash Command 联动：user-invocable Skill 会暴露为 slash command

9.3 ClawHub 技能市场

10. 未来展望

10.1 AI 工具演进三阶段

10.2 Skills 的定位

"Skills 不只是一个新功能，它是让 AI 从'对话机器人'变成'数字工匠'的关键一步。"

10.3 企业级应用方向

1. CI/CD 与评估飞轮：将每个 Skill 视为软件包
2. 元数据安全：对 description 做质量门控
3. 最小权限与分层隔离：deny-wins 策略
4. Scripts 供应链治理：强制审计第三方 scripts
5. 优先"确定性外包"：解析、验证、格式化任务优先写脚本
6. MCP + Skills 组合：MCP 暴露工具，Skills 作为 SOP
7. 渐进式采用：先在隔离环境验证

总结

Claude Code Skills 代表了 AI Agent 从"聊天工具"向"生产力操作系统"的进化。通过渐进式披露架构、开放标准化、丰富的生态资源，Skills 正在成为 2026 年 AI Agent 开发的核心范式。