Claude Code Skill 使用指南：两种接入方式详解Claude Code Skill 使用指南：两种接入方式

Claude Code Skill 使用指南:两种接入方式详解

Claude Code 的 Skill 系统让 AI 编程助手从"能用"变成"好用"。本文以两个主流社区仓库为例,讲清楚两种接入方式的区别,并以 test-driven-development 为实战案例,演示有无 Skill 的真实差异。

什么是 Claude Code Skill?

Skill 是一种可复用的工作流指令,本质上是一个 Markdown 文件(SKILL.md),告诉 Claude 在特定场景下该怎么做事。安装后,Claude Code 会在合适的时机自动读取并遵循这些指令,无需每次手动说明。

举个类比:如果你雇了一个程序员,你可以给他一份《开发规范手册》,之后他每次写代码都会自动遵守规范,而不需要你反复强调。Skill 就是这份手册。

目前社区最活跃的两个 Skill 仓库:

obra/superpowers:一套完整的 AI 编程工作流,涵盖 TDD、代码审查、分支管理等全链路
ComposioHQ/awesome-claude-skills:聚合了社区贡献的各类 Skill,涵盖文档处理、数据分析、SaaS 集成等

此外,Anthropic 官方也维护一个 anthropics/skills 仓库,里面包括 frontend-design、docx、pptx、xlsx、pdf、skill-creator 等官方精心维护的 Skill,同样可以按下面的方式接入。

两种接入方式

方式一:Plugin 插件接入(推荐)

适用仓库:obra/superpowers、anthropics/skills

Plugin 方式是官方支持的接入方式,通过 Claude Code 内置的插件市场一键安装,全局生效,更新也只需一条命令。

安装步骤:

# 方法 1:官方 Marketplace(最简单)
/plugin install superpowers@claude-plugins-official

# 方法 2:注册第三方市场再安装
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# 方法 3:安装 Anthropic 官方的文档/示例 Skill 包
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

安装完成后无需任何配置,重启 Claude Code 即生效。

更新:

/plugin update superpowers

优点:

一键安装,零配置
官方维护,自动更新
Skills 会随插件版本统一升级
支持多平台(Cursor、Copilot CLI、Gemini CLI 等)

目录结构(插件内部):

superpowers/
├── .claude-plugin/       ← Claude Code 插件入口
├── skills/
│   ├── test-driven-development/
│   │   ├── SKILL.md
│   │   └── testing-anti-patterns.md
│   ├── brainstorming/
│   ├── using-git-worktrees/
│   └── ...
└── CLAUDE.md

方式二:`~/.claude/skills/` 目录接入(手动)

适用仓库:ComposioHQ/awesome-claude-skills、anthropics/skills,以及任何包含 SKILL.md 的仓库

手动方式是将 Skill 文件夹直接放到 Claude Code 的 skills 目录,按需安装,灵活选择你需要的 Skill。

两种路径的作用范围

Claude Code 启动时会扫描两个位置:

路径	作用范围	适合场景
`~/.claude/skills/`	全局,所有项目生效	个人常用 Skill
`项目根目录/.claude/skills/`	仅当前项目生效	团队共享、项目专用规范(通常提交到 git)

注意:旧文档里偶尔会看到 ~/.config/claude-code/skills/ 这种写法,那是早期社区配置的残留,当前官方路径是 ~/.claude/skills/ ,Claude Code 只会扫描这个目录。

安装步骤(以 awesome-claude-skills 为例)

# 第一步:创建全局 Skills 目录(首次使用)
mkdir -p ~/.claude/skills/

# 第二步:下载仓库
git clone https://github.com/ComposioHQ/awesome-claude-skills.git /tmp/awesome-skills

# 网络受限时,浏览器下载 ZIP 后解压到 /tmp/awesome-skills:
# https://github.com/ComposioHQ/awesome-claude-skills/archive/refs/heads/master.zip

# 第三步:复制需要的 Skill(只选你要的,不要整仓库丢进去)
cp -r /tmp/awesome-skills/changelog-generator ~/.claude/skills/
cp -r /tmp/awesome-skills/mcp-builder          ~/.claude/skills/
cp -r /tmp/awesome-skills/webapp-testing       ~/.claude/skills/

# 第四步:验证目录结构
ls ~/.claude/skills/
# 应该看到:changelog-generator  mcp-builder  webapp-testing

安装 Anthropic 官方 Skill 示例

官方仓库的 Skill 在 skills/skills/ 子目录下(第一层是仓库根,第二层才是各个 skill):

git clone https://github.com/anthropics/skills.git /tmp/anthropic-skills

# 注意是 skills/skills/ 两层
cp -r /tmp/anthropic-skills/skills/frontend-design ~/.claude/skills/
cp -r /tmp/anthropic-skills/skills/skill-creator   ~/.claude/skills/

# 一次装多个也可以
cp -r /tmp/anthropic-skills/skills/{frontend-design,docx,xlsx,pptx,pdf} ~/.claude/skills/

项目级安装(仅对当前项目生效)

mkdir -p your-project/.claude/skills/
cp -r /tmp/awesome-skills/changelog-generator your-project/.claude/skills/

项目级 Skill 会跟着仓库一起 commit,团队成员 clone 之后自动生效,非常适合统一代码规范。

最终目录长这样

~/.claude/skills/
├── changelog-generator/
│   └── SKILL.md
├── frontend-design/
│   ├── SKILL.md
│   └── references/
├── mcp-builder/
│   └── SKILL.md
└── test-driven-development/
    ├── SKILL.md
    └── testing-anti-patterns.md

关键点: 每个 Skill 文件夹的第一层必须直接是 SKILL.md。最常见的踩坑是多套了一层目录,比如 ~/.claude/skills/awesome-skills-master/changelog-generator/SKILL.md——这样 Claude Code 识别不到,要把最外层的 awesome-skills-master/ 扁平掉。

优点:

按需安装,不引入用不到的 Skill
可以混搭来自不同仓库的 Skill
可以直接编辑 SKILL.md 做自定义调整

使用 `/skills` 命令验证安装

装完之后,一定要验证一下是否被 Claude Code 识别。在任意项目目录启动 Claude Code:

claude

然后在交互界面输入:

/skills

回车后会弹出一个 Skill 列表,你刚安装的 Skill 应该出现在里面,例如:

Available skills:

Personal (~/.claude/skills/)
  /changelog-generator    Generate changelogs from git commits
  /frontend-design        Create distinctive, production-grade frontend interfaces
  /mcp-builder            Scaffold MCP servers
  /test-driven-development  Enforce RED → GREEN → REFACTOR workflow
  /webapp-testing         End-to-end webapp testing workflow

Project (.claude/skills/)
  (none)

Bundled
  /simplify    /batch    /debug    /loop    /claude-api

如果没看到你刚装的 Skill,排查这四件事:

目录层级错了——确认路径是 ~/.claude/skills/<skill-name>/SKILL.md,中间不要多一层
SKILL.md 大小写错了——文件名必须是全大写 SKILL.md
YAML frontmatter 缺失或语法错——文件开头必须有 --- name: ... description: ... --- 这一段
没重启会话——改动完要退出当前 claude 会话再重新进

也可以用一行命令先肉眼快速检查:

find ~/.claude/skills -maxdepth 2 -name SKILL.md

每一行输出对应一个能被 Claude Code 识别的 Skill。

直接调用 Skill

/skills 不光是查看列表,还能直接点选或用斜杠调用:

/test-driven-development 帮我实现购物车总价计算

Claude Code 会显式加载这个 Skill 的完整内容,然后按指令执行。相比让它自动触发,显式调用能保证 100% 生效,适合关键任务。

两种方式对比总结

对比项	Plugin 插件方式	`~/.claude/skills/` 目录方式
代表仓库	obra/superpowers、anthropics/skills	ComposioHQ/awesome-claude-skills、anthropics/skills
安装方式	一条 `/plugin install` 命令	`git clone` + `cp -r`
更新方式	`/plugin update`	手动 `git pull` 后重新 `cp -r`
灵活性	整包安装	按需挑选单个 Skill
自定义	较难修改(插件文件受管理)	直接编辑 `SKILL.md`
验证方式	`/plugin` 列表 + `/skills`	`/skills`
适合场景	完整工作流、团队统一	单点能力扩展、个人定制

实战对比:有无 TDD Skill 的区别

以 test-driven-development Skill 为例,直观感受差异。

场景:实现一个购物车计算总价的函数

❌ 不使用 TDD Skill 时

你输入:

帮我写一个计算购物车总价的函数,支持折扣和税率

Claude 的典型回应(直接给实现):

// Claude 直接输出实现代码
function calculateTotal(items, discount = 0, taxRate = 0) {
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discounted = subtotal * (1 - discount);
  const total = discounted * (1 + taxRate);
  return Math.round(total * 100) / 100;
}

问题:

没有测试,你不知道边界情况有没有处理(比如 discount > 1 怎么办?items 为空怎么办?)
代码可能一次性写对了,也可能有隐藏 bug
后续修改时没有安全网

✅ 使用 TDD Skill 时

安装 Skill 后,你输入同样的内容,Claude 会宣告:

我将使用 test-driven-development skill 来实现这个功能。

然后严格按照 RED → GREEN → REFACTOR 三步走:

🔴 第一步:先写失败的测试

// cart.test.js
import { calculateTotal } from './cart.js';

describe('calculateTotal', () => {
  test('正常计算总价', () => {
    const items = [      { price: 100, quantity: 2 },      { price: 50, quantity: 1 },    ];
    expect(calculateTotal(items)).toBe(250);
  });

  test('应用折扣', () => {
    const items = [{ price: 100, quantity: 1 }];
    expect(calculateTotal(items, 0.1)).toBe(90);
  });

  test('应用税率', () => {
    const items = [{ price: 100, quantity: 1 }];
    expect(calculateTotal(items, 0, 0.08)).toBe(108);
  });

  test('空购物车返回 0', () => {
    expect(calculateTotal([])).toBe(0);
  });

  test('折扣超过 100% 时抛出错误', () => {
    expect(() => calculateTotal([{ price: 100, quantity: 1 }], 1.5))
      .toThrow('折扣不能超过 100%');
  });
});

运行测试,确认全部红色(失败):

$ npm test

FAIL cart.test.js
  ✕ 正常计算总价 (TypeError: calculateTotal is not a function)
  ✕ 应用折扣
  ✕ 应用税率
  ✕ 空购物车返回 0
  ✕ 折扣超过 100% 时抛出错误

🟢 第二步:写最少的代码让测试通过

// cart.js
export function calculateTotal(items, discount = 0, taxRate = 0) {
  if (discount > 1) throw new Error('折扣不能超过 100%');
  if (items.length === 0) return 0;

  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  const discounted = subtotal * (1 - discount);
  const total = discounted * (1 + taxRate);
  return Math.round(total * 100) / 100;
}

再次运行测试,确认全部绿色(通过):

$ npm test

PASS cart.test.js
  ✓ 正常计算总价 (3ms)
  ✓ 应用折扣 (1ms)
  ✓ 应用税率 (1ms)
  ✓ 空购物车返回 0 (1ms)
  ✓ 折扣超过 100% 时抛出错误 (2ms)

Tests: 5 passed, 5 total

🔵 第三步:重构,保持测试绿色

// cart.js(重构后更清晰)
export function calculateTotal(items, discount = 0, taxRate = 0) {
  validateDiscount(discount);

  const subtotal = computeSubtotal(items);
  const afterDiscount = applyDiscount(subtotal, discount);
  const total = applyTax(afterDiscount, taxRate);

  return roundCurrency(total);
}

function validateDiscount(discount) {
  if (discount > 1) throw new Error('折扣不能超过 100%');
}

function computeSubtotal(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

function applyDiscount(amount, discount) {
  return amount * (1 - discount);
}

function applyTax(amount, taxRate) {
  return amount * (1 + taxRate);
}

function roundCurrency(amount) {
  return Math.round(amount * 100) / 100;
}

两种方式的核心差异

对比项	不用 TDD Skill	用 TDD Skill
写代码顺序	直接写实现	先写测试,再写实现
边界情况	可能遗漏	测试先行,强制覆盖
验证方式	眼睛看/手动测	自动化测试验证
重构安全感	改了不知道有没有破坏	测试是安全网
输出质量	取决于 Claude 状态	流程保证,稳定可靠

Skill 的触发规则

自动触发(无需声明): 安装后,只要你的请求涉及写代码或修复 Bug,TDD Skill 就会自动介入。

你:帮我实现用户登录功能
Claude:我将使用 test-driven-development skill...(自动触发)

显式触发: 在对话里用斜杠命令直接调用,确保 100% 生效。

/test-driven-development 帮我实现用户登录功能

优先级顺序:

用户明确指令(CLAUDE.md 或对话中直接说)  ← 最高优先级
           ↓
Skill 规则(自动执行)
           ↓
Claude 默认行为                            ← 最低优先级

临时跳过 TDD: 直接在对话中说

跳过 TDD,直接给我实现代码

永久禁用 TDD: 在项目根目录的 CLAUDE.md 里加一行

不要使用 TDD,直接实现功能

常见问题排查

Q1:/skills 里看不到我刚装的 Skill

按顺序检查:

# 1. 路径是否正确?
ls ~/.claude/skills/

# 2. SKILL.md 是否在第一层?(不能多套目录)
find ~/.claude/skills -maxdepth 2 -name SKILL.md

# 3. 文件名大小写是否正确?
ls ~/.claude/skills/your-skill/SKILL.md   # 必须全大写

# 4. frontmatter 是否完整?
head -5 ~/.claude/skills/your-skill/SKILL.md
# 应该看到 --- name: ... description: ... ---

最后退出 Claude Code 重新 claude 一次。

Q2:Skill 装了但不自动触发

Skill 的触发靠 description 字段里的关键词匹配。如果描述写得不够具体,Claude 可能判断不出要用。解决办法:

在请求里主动用斜杠命令调用:/your-skill 做某事
或者编辑 SKILL.md 的 frontmatter,让 description 更明确地列出触发场景

Q3:想临时禁用某个 Skill

改名加个下划线前缀就行,Claude Code 不会加载非标准命名的目录:

mv ~/.claude/skills/code-reviewer ~/.claude/skills/_code-reviewer

想恢复就改回来。

小结

Claude Code 的 Skill 系统提供了两种接入路径:

Plugin 方式适合想要开箱即用、完整工作流的团队,推荐直接安装 obra/superpowers,一条命令搞定
~/.claude/skills/ 方式适合希望精细控制、按需组合的开发者,从 ComposioHQ/awesome-claude-skills 或 anthropics/skills 选取需要的 Skill 手动复制安装

两种方式并不互斥,完全可以同时使用。Plugin 提供完整工作流,目录方式补充单点能力。不管哪种方式,装完都用 /skills 验证一遍——确认 Claude Code 能识别到,才算真正装好。

TDD Skill 是最值得第一个安装的 Skill——它改变的不只是 Claude 的输出结果,而是整个写代码的思维顺序:先想清楚要验证什么,再去实现它。这恰好是 AI 辅助编程最容易出问题的地方。

相关链接

Claude Code 官方 Skill 文档:code.claude.com/docs/en/ski…

Anthropic 官方 Skill 仓库:github.com/anthropics/…

obra/superpowers:github.com/obra/superp…

ComposioHQ/awesome-claude-skills:github.com/ComposioHQ/…

Claude Code Skill 使用指南：两种接入方式详解