Claude Code Skills学习笔记

基于 Anthropic 官方文档、agentskills.io 开放标准及社区最佳实践整理
最后更新：2026-08-17

目录

  1. 什么是 Claude Code Skills
  2. Skill 的核心概念
  3. Skill 与相关技术的区别
  4. 安装与发现路径
  5. SKILL.md 文件格式详解
  6. Claude Code 特有的扩展字段
  7. 创建你的第一个 Skill
  8. 使用 Skill 的两种方式
  9. 内置 Bundled Skills
  10. 通过插件市场安装 Skill
  11. Skill 的最佳实践
  12. 安全注意事项
  13. 跨平台兼容性
  14. 常见问题 FAQ

1. 什么是 Claude Code Skills

Claude Code Skill 是一个包含 SKILL.md 文件（以及可选的脚本、模板或参考文档）的文件夹。Claude Code 会自动扫描并发现这些 Skill，当当前任务与 Skill 的描述匹配时，自动加载并执行其中的指令。

Skill 的本质是可复用的专家知识——将"我们如何在这个项目中交付一个 Next.js 功能"这样的团队经验编码为 Claude 可以自动遵循的剧本。

核心特点

  • 自动发现：Claude Code 在每次会话启动时自动扫描 Skill 目录
  • 按需加载：仅在任务匹配时才加载完整内容，保持上下文窗口精简
  • 跨会话持久：一次编写，多次复用，无需每次重新提示
  • 开放标准：遵循 agentskills.io 规范，可在多个 AI 工具间通用

2. Skill 的核心概念

2.1 渐进式加载（Progressive Disclosure）

Skill 采用三层加载策略，这是其高效的关键：

阶段 加载内容 时机 大小
启动时 仅 frontmatter 中的 name + description 每次会话开始 ~50-100 tokens/Skill
匹配时 完整的 SKILL.md Markdown 内容 任务描述匹配时 视内容而定
执行时 引用的辅助脚本、模板文件 指令需要时 按需加载

这意味着你可以安装几十个 Skill 而不会膨胀上下文窗口——Claude 只在需要时才加载完整内容。

2.2 两种 Skill 类型

类型 说明 示例
能力增强型 (Capability Uplift) 赋予 Claude 原本不具备的能力 Web 爬虫、PDF 处理、浏览器测试
偏好编码型 (Encoded Preference) 编码团队特定的工作方式 代码审查清单、提交消息格式、设计规范

2.3 三个作用域

作用域 路径 可见范围 用途
个人级 ~/.claude/skills/ 所有项目 个人工作流优化
项目级 .claude/skills/ 当前仓库（通过 Git 共享） 团队规范与约定
企业级 管理员部署 组织内所有成员 企业统一标准

优先级：企业级 > 个人级 > 项目级

3. Skill 与相关技术的区别

3.1 Skill vs MCP Server

对比项 Skill MCP Server
本质 文件夹 + Markdown 指令 外部持久进程
协议 文件系统读取 Model Context Protocol (JSON-RPC)
作用 "怎么做"（流程/知识） "做什么"（工具/数据连接）
类比 员工手册 USB 接口
状态 无状态，按需加载 有状态，持续运行

关系：Skill 可以调用 MCP Server 提供的工具，两者互补。

3.2 Skill vs Hook

对比项 Skill Hook
触发方式 任务匹配（模型决定） 事件驱动（确定性）
用途 可复用专业知识 确定性副作用（如保存时运行 prettier）
示例 "如何添加新功能" "每次保存后自动格式化"

3.3 Skill vs CLAUDE.md

对比项 Skill CLAUDE.md
加载时机 按需（任务匹配时） 每轮都加载
适用场景 特定工作流 全局风格/规则
成本 低（仅需要时加载） 高（每轮都占 token）

建议：CLAUDE.md 用于始终适用的全局规则；Skill 用于特定场景的工作流。

3.4 Skill vs 传统 Slash Command

2026 年，Anthropic 已将自定义命令合并到 Skills 中：

特性 传统 Slash Command Skill
路径 .claude/commands/review.md .claude/skills/review/SKILL.md
触发 手动 (/review) 自动 + 手动
辅助文件 不支持 支持（模板、脚本等）
前置元数据 可选 支持（调用控制、工具限制等）

现有命令文件仍兼容，但 Skill 是推荐方式。

4. 安装与发现路径

4.1 手动安装（推荐用于自定义 Skill）

# 个人级 Skill（全局可用）
mkdir -p ~/.claude/skills/my-skill/

# 项目级 Skill（随仓库共享）
mkdir -p .claude/skills/my-skill/

然后在文件夹中创建 SKILL.md 文件。

4.2 通过插件市场安装

# 添加官方 Skill 仓库
/plugin marketplace add anthropics/skills

# 安装特定 Skill
/plugin install pdf
/plugin install webapp-testing

# 或通过 Vercel 的 skills CLI
npx skills add https://github.com/anthropics/skills --skill pdf

4.3 通过 skills.sh 安装

# 安装社区 Skill
npx skills add forrestchang/andrej-karpathy-skills
npx skills add vercel-labs/agent-skills --skill web-design-guidelines

4.4 激活新 Skill

# 方式一：重启 Claude Code
# 方式二：使用热重载命令
/reload-skills

5. SKILL.md 文件格式详解

每个 SKILL.md 包含两部分：YAML Frontmatter + Markdown 指令内容。

5.1 最小示例

---
name: daily-standup
description: Generate a daily standup summary from git activity
---

Summarize today's git commits into a standup format:
1. What I did yesterday
2. What I'm doing today
3. Any blockers

5.2 完整 Frontmatter 字段（agentskills.io 标准）

字段 必需 约束 说明
name ✅ 1-64 字符，小写/数字/连字符，不能首尾为连字符，不能连续连字符 Skill 标识符，也作为 slash 命令名
description ✅ 1-1024 字符，非空 Skill 描述，Claude 用它来判断是否匹配任务
license ❌ 建议简短 许可证名称或引用捆绑的许可证文件
compatibility ❌ 最多 500 字符 环境要求（如需要 Python 3.14+、Docker 等）
metadata ❌ 字符串键值对映射 额外元数据（作者、版本等）
allowed-tools ❌ 空格分隔的工具名 实验性：预批准的工具列表

name 字段规则

# ✅ 有效
name: pdf-processing
name: data-analysis
name: code-review

# ❌ 无效
name: PDF-Processing      # 大写不允许
name: -pdf                # 不能以连字符开头
name: pdf--processing     # 不能连续连字符
name: pdf_processing      # 下划线不允许

description 字段最佳实践

# ✅ 好的描述（具体、包含关键词）
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.

# ❌ 差的描述（太模糊）
description: Helps with PDFs.

5.3 Markdown 内容结构建议

虽然内容完全自由，但高效的 Skill 通常包含以下部分：

---
name: new-feature
description: Scaffold a new Next.js feature with route, component, and test.
---

# New Feature

## Overview
Scaffold a new Next.js feature with route, component, and test, then run the linter and unit tests.

## Input Requirements
- Feature name
- Target route path

## Step-by-Step Instructions
1. Confirm the feature name and target route with the user (one short clarifying question).
2. Create `app/ROUTE/page.tsx` from `templates/page.tsx`.
3. Create `app/ROUTE/Component.tsx` from `templates/component.tsx`.
4. Create `app/ROUTE/Component.test.tsx` from `templates/component.test.tsx`.
5. Run `npm run lint` and `npm test -- ROUTE`.
6. Summarize what was added and what the user should review before commit.

## Conventions
- TypeScript only. No JS files.
- Components use the project's design system (see `lib/ui`).
- Tests use Vitest plus React Testing Library.

## Output Format
- Summary of created files
- Test results
- Lint results

6. Claude Code 特有的扩展字段

Claude Code 在 agentskills.io 标准基础上增加了以下字段：

字段 类型 说明
disable-model-invocation boolean 设为 true 时禁止自动触发，用户必须手动输入 /skill-name
user-invocable boolean 设为 false 时从 / 菜单中隐藏，仅作为背景知识
argument-hint string 自动补全提示，如 [filename] [format]
model string 激活此 Skill 时覆盖使用的模型（如 opus）
context string 设为 fork 时在子代理（subagent）中运行
agent string 当 context: fork 时指定子代理类型（如 Explore）

6.1 完整示例（含扩展字段）

---
name: code-review
description: Reviews the current diff for correctness and quality. Use when the user asks for code review, PR review, or asks to check code changes.
disable-model-invocation: false
user-invocable: true
allowed-tools: Read Grep Bash(git:diff)
argument-hint: [file-path]
model: opus
---

# Code Review Skill

## Process
1. Run `git diff` to get the current changes.
2. Analyze each changed file for:
   - Bugs and logic errors
   - Security vulnerabilities
   - Performance issues
   - Style violations
   - Missing tests
3. Provide specific, actionable feedback with line references.

## Constraints
- Focus on critical issues first
- Suggest concrete fixes, not just flag problems
- Be concise but thorough

6.2 重要注意事项

⚠️ 不同分发路径的 Schema 差异

  • 可移植标准路径（claude.ai/Team 上传、Skills API、scripts/package_skill.py）：仅允许 name, description, license, compatibility, metadata, allowed-tools
  • Claude Code 插件路径（marketplace 安装）：额外支持 argument-hint, disable-model-invocation, user-invocable 等字段

如果在标准路径中使用扩展字段，打包时会报错：

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

7. 创建你的第一个 Skill

7.1 步骤概览

  1. 确定范围：选择一个你经常重复的工作流
  2. 选择位置：个人级 (~/.claude/skills/) 或项目级 (.claude/skills/)
  3. 创建文件夹：文件夹名将成为 Skill 名
  4. 编写 SKILL.md：包含 frontmatter 和指令内容
  5. 添加辅助文件（可选）：脚本、模板、参考文档
  6. 测试激活：重启 Claude Code 或运行 /reload-skills

7.2 实战示例：Next.js 功能脚手架

目录结构：

~/.claude/skills/new-feature/
├── SKILL.md
└── templates/
    ├── page.tsx
    ├── component.tsx
    └── component.test.tsx

SKILL.md：

---
name: new-feature
description: Scaffold a new Next.js feature with route, component, and test, then run the linter and unit tests. Use when the user asks to add a new feature, page, or screen to this codebase.
---

# New Feature

When the user asks to add a new feature, page, or screen to this codebase, use this Skill.

## Steps

1. Confirm the feature name and target route with the user (one short clarifying question).
2. Create `app/ROUTE/page.tsx` from `templates/page.tsx`.
3. Create `app/ROUTE/Component.tsx` from `templates/component.tsx`.
4. Create `app/ROUTE/Component.test.tsx` from `templates/component.test.tsx`.
5. Run `npm run lint` and `npm test -- ROUTE`.
6. Summarize what was added and what the user should review before commit.

## Conventions

- TypeScript only. No JS files.
- Components use the project's design system (see `lib/ui`).
- Tests use Vitest plus React Testing Library.

templates/page.tsx：

export default function Page() {
  return (
    <main>
      <h1>{{FEATURE_NAME}}</h1>
    </main>
  );
}

7.3 使用 Skill Creator 自动生成

Anthropic 提供了交互式 Skill 生成器：

/plugin marketplace add anthropics/skills
/plugin install skill-creator

然后使用：

Use the skill-creator to help me build a skill for running database migrations safely

它会通过问答引导你生成完整的 Skill 结构。

8. 使用 Skill 的两种方式

8.1 自动触发（推荐）

只需用自然语言描述任务，Claude Code 会自动匹配并加载相关 Skill：

You: Add a new "subscribers" table with email + plan, then ship the project to staging.

Claude: I see your ship-totalum-app Skill in this repo. Loading it...
Claude: (reads SKILL.md, runs scaffold-schema.sh, calls Totalum MCP create-table tool...)
Claude: Subscribers table created. Staging URL: https://app-staging.totalum.app/...

8.2 手动触发

当需要确定性调用或存在多个匹配 Skill 时：

# 基础语法
/skill ship-totalum-app run with table=subscribers

# 或使用 Skill 名作为 slash 命令
/new-feature pricing-page

# 带参数
/code-review src/components/**/*.tsx

9. 内置 Bundled Skills

Claude Code 自带一组无需编写即可使用的 Skill：

Skill 命令 功能
Doctor /doctor 设置和配置检查
Code Review /code-review 审查当前 diff 的正确性和质量
Verify /verify 构建并运行应用，确认更改实际有效
Run /run 启动并驱动应用
Debug /debug 调试辅助
Batch /batch 批处理
Loop /loop 按间隔重复执行提示
Claude API /claude-api Claude API 参考

禁用内置 Skills：

{
  "disableBundledSkills": true
}

注意：禁用后 /doctor 仍可用。

10. 通过插件市场安装 Skill

10.1 官方 Skill 仓库

# 添加官方市场
/plugin marketplace add anthropics/skills

# 安装 Skill 集合
/plugin install pdf
/plugin install webapp-testing
/plugin install doc-coauthoring

10.2 社区 Skill 仓库

# Vercel Labs
npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices

# Firecrawl
npx skills add https://github.com/firecrawl/skills --skill firecrawl

# Trail of Bits（安全审计）
npx skills add trailofbits/skills

# Remotion（视频制作）
npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices

10.3 热门 Skill 推荐

Skill 作者 类型 安装命令
Frontend Design Anthropic 偏好编码 npx skills add https://github.com/anthropics/skills --skill frontend-design
Web Design Guidelines Vercel 偏好编码 npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines
React Best Practices Vercel 偏好编码 npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices
PDF Processing Anthropic 能力增强 npx skills add https://github.com/anthropics/skills --skill pdf
Webapp Testing Anthropic 能力增强 npx skills add https://github.com/anthropics/skills --skill webapp-testing
Andrej Karpathy Skills Forrest Chang 偏好编码 npx skills add forrestchang/andrej-karpathy-skills
Caveman Julius Brussee 偏好编码 npx skills add mattpocock/skills --skill caveman -g

11. Skill 的最佳实践

11.1 编写 SKILL.md 的原则

✅ 好的做法 ❌ 避免的做法
描述像路由规则一样具体 模糊描述如 "Helps with documents"
代码做确定性工作（排序、解析、验证） 让模型做这些工作
精简 SKILL.md，详细内容放参考文件 4000 token 的巨型 SKILL.md
一个 Skill 只做一件事 一个 Skill 试图做五件事
用示例代替规则 20 条抽象约束
首行描述以结果为导向、使用祈使句 模糊的目标描述
正文控制在 1500 词以内 冗长的散文式说明
使用明确的编号步骤 模糊的段落描述
通过相对路径引用辅助文件 内联巨大的 schema

11.2 目录结构建议

.claude/skills/
├── code-review/
│   ├── SKILL.md
│   └── checklist.md          # 审查清单参考
├── new-feature/
│   ├── SKILL.md
│   └── templates/            # 代码模板
│       ├── page.tsx
│       └── component.tsx
└── deploy/
    ├── SKILL.md
    └── scripts/
        └── pre-deploy.sh     # 预部署检查脚本

11.3 描述优化技巧

# ✅ 好的描述（Claude 能可靠匹配）
description: Extract form fields, fill, redact, or parse tables from a PDF file. Use when the user uploads or mentions PDF documents.

# ❌ 差的描述（Claude 无法可靠路由）
description: Helps with documents.
description: Use this for productivity tasks.

11.4 测试 Skill 的可靠性

用 5 种不同的措辞测试同一个请求，确保 Skill 能一致触发：

"帮我审查这段代码"
"看看这个 PR 有没有问题"
"检查一下我刚写的函数"
"code review please"
"能帮我看看这些改动吗"

12. 安全注意事项

12.1 Skill 供应链风险

  • Skill 会在你的机器上执行代码（通过 Claude 调用工具）
  • 2026 年 2 月 Snyk 审计发现 36.82% 的公开 Skill 存在至少一个安全漏洞，13.4% 存在严重问题
  • 36% 的测试 Skill 存在提示注入风险

12.2 安全使用建议

  1. 审查再安装：像审查开源依赖一样审查 Skill，阅读完整的 SKILL.md 和每个捆绑脚本
  2. 固定版本：通过 Git tag 或 commit SHA 安装，不要跟踪 main 分支
  3. 使用可信来源：优先使用 anthropics/skills、vercel-labs/agent-skills 等官方/知名仓库
  4. 隔离运行：为每个客户/项目使用独立的工作目录或容器
  5. 扫描工具：使用 Snyk Agent Scan 等工具扫描社区 Skill
  6. 结合 Hook 防护：使用 PreToolUse Hook 在危险命令执行前拦截

12.3 危险信号

  • Skill 包含未记录的网络调用
  • 脚本执行你不理解的 shell 命令
  • 要求访问敏感文件或环境变量
  • 来源不明的社区 Skill

13. 跨平台兼容性

13.1 Agent Skills 开放标准

Anthropic 于 2025 年 12 月 18 日 将 Skill 格式发布为开放标准（agentskills.io），截至 2026 年中已有约 40 个平台支持：

  • Anthropic: Claude Code, Claude Apps, Claude API
  • OpenAI: Codex CLI
  • Google: Gemini CLI
  • Microsoft: GitHub Copilot, VS Code
  • 编辑器: Cursor, JetBrains Junie, Kiro, Trae, Roo Code
  • 开源: OpenCode, Amp, Goose, OpenHands, Factory, Mistral Vibe
  • 平台: Snowflake Cortex Code, Databricks Genie Code, Pulumi Neo, Tabnine

13.2 各平台目录约定

平台 个人级路径 项目级路径
Claude Code ~/.claude/skills/ .claude/skills/
Codex CLI ~/.codex/skills/ .codex/skills/ 或 .agents/skills/
GitHub Copilot - .github/skills/
Cursor - .cursor/skills/

13.3 跨平台兼容技巧

如需在多个工具间共享 Skill，使用核心规范字段（name, description, Markdown body），避免使用 Claude Code 特有的扩展字段：

# 创建统一目录并建立符号链接
mkdir -p .skills/code-review
ln -s ../../.skills .claude/skills
ln -s ../../.skills .agents/skills
ln -s ../../.skills .github/skills

14. 常见问题 FAQ

Q1: Skill 和 MCP Server 有什么区别？

A: MCP Server 提供工具（如连接数据库、发送邮件），Skill 提供知识（如"如何添加新功能"的流程）。Skill 可以调用 MCP Server 的工具。类比：MCP 是 USB 接口，Skill 是员工手册。

Q2: 如何安装 Claude Code Skill？

A: 三种方式：

  1. 手动：在 ~/.claude/skills/ 或 .claude/skills/ 创建文件夹并放入 SKILL.md
  2. 插件市场：/plugin marketplace add REPO 然后 /plugin install SKILL
  3. CLI：npx skills add OWNER/REPO --skill SKILL-NAME

Q3: Skill 会自动触发吗？

A: 是的。Claude Code 会在每次会话开始时扫描 Skill 目录，读取 name 和 description。当你描述任务时，Claude 会自动匹配并加载相关 Skill。你也可以手动触发：/skill-name。

Q4: 内置的 Bundled Skills 有哪些？

A: /doctor, /code-review, /verify, /run, /debug, /batch, /loop, /claude-api。可用 disableBundledSkills 设置关闭。

Q5: 一个项目可以有多少个 Skill？

A: 没有硬性限制。由于渐进式加载机制，即使有几十个 Skill，启动时也只加载 name + description（约 100 tokens/个），不会膨胀上下文窗口。

Q6: Skill 可以调用其他 Skill 吗？

A: 可以。Claude Code 支持多个 Skill 同时激活，Skill 是模块化设计的，可以协同工作。

Q7: 如何调试 Skill 不触发的问题？

A:

  1. 检查 description 是否足够具体，包含用户可能使用的关键词
  2. 用 /reload-skills 确认 Skill 已被加载
  3. 尝试用不同措辞描述任务
  4. 检查是否有 disable-model-invocation: true
  5. 确认 Skill 文件路径正确（必须在 SKILL.md 同级目录下）

Q8: Skill 中的脚本安全吗？

A: Skill 中的脚本由 Claude 根据指令调用，会在你的机器上执行。务必审查每个脚本的内容，只安装来自可信来源的 Skill。

Q9: 旧版的 .claude/commands/ 还能用吗？

A: 可以。文件 .claude/commands/deploy.md 和 Skill .claude/skills/deploy/SKILL.md 都会创建 /deploy 命令且行为相同。但 Skill 格式是推荐方式。

Q10: 如何分享 Skill 给团队？

A: 将 Skill 放在项目级的 .claude/skills/ 目录中并提交到 Git。这样团队成员克隆仓库后即可自动使用。

参考资源

本文档基于 Anthropic 官方文档、agentskills.io 开放标准及社区最佳实践整理，持续更新中。

posted @ 2026-09-15 12:48  RK5123153  阅读(50)  评论(0)    收藏  举报