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：⭐ 137k，一套完整的 AI 编程工作流，涵盖 TDD、代码审查、分支管理等全链路
• ComposioHQ/awesome-claude-skills：⭐ 41k，聚合了社区贡献的各类 Skill，涵盖文档处理、数据分析、SaaS 集成等

---

两种接入方式

方式一：Plugin 插件接入（推荐）

适用仓库：obra/superpowers

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

安装步骤：

# 方法 1：官方 Marketplace（最简单）
/plugin install superpowers@claude-plugins-official

# 方法 2：通过注册第三方市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

安装完成后无需任何配置，重启 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

---

方式二：.config 目录接入（手动）

适用仓库：ComposioHQ/awesome-claude-skills

.config 方式是将 Skill 文件直接放到 Mac 本地配置目录，按需安装，灵活选择你需要的 Skill。

全局安装路径：

~/.config/claude-code/skills/

放在这个路径下的 Skill，在你 Mac 上任意目录启动 claude 都会生效。

安装步骤：

# 第一步：创建全局 Skills 目录
mkdir -p ~/.config/claude-code/skills/

# 第二步：下载仓库（网络正常时）
git clone https://github.com/ComposioHQ/awesome-claude-skills.git /tmp/awesome-skills

# 网络受限时，浏览器下载 ZIP：
# https://github.com/ComposioHQ/awesome-claude-skills/archive/refs/heads/master.zip

# 第三步：复制需要的 Skill
cp -r /tmp/awesome-skills/changelog-generator ~/.config/claude-code/skills/
cp -r /tmp/awesome-skills/mcp-builder ~/.config/claude-code/skills/
cp -r /tmp/awesome-skills/webapp-testing ~/.config/claude-code/skills/

# 第四步：验证
ls ~/.config/claude-code/skills/

项目级安装（仅对当前项目生效）：

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

优点：

• 按需安装，不引入不需要的 Skill
• 可以安装来自不同仓库的 Skill 自由组合
• 支持自定义修改 SKILL.md 内容

两种路径对比：

路径	作用范围
~/.config/claude-code/skills/	全局，所有项目生效
项目根目录/.claude/skills/	仅当前项目生效

---

两种方式对比总结

对比项	Plugin 插件方式	.config 目录方式
代表仓库	obra/superpowers	ComposioHQ/awesome-claude-skills
安装方式	一条命令	手动复制文件
更新方式	/plugin update	手动重新下载
灵活性	整包安装	按需选择
自定义	较难修改	直接编辑 SKILL.md
适合场景	完整工作流	单点能力扩展

---

实战对比：有无 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...（自动触发）

优先级顺序：

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

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

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

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

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

---

小结

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

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

两种方式并不互斥，完全可以同时使用。Plugin 提供完整工作流，.config 补充单点能力。

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

---

相关链接

• obra/superpowers：github.com/obra/superp…
• awesome-claude-skills：github.com/ComposioHQ/…
• Claude Code 官方文档：docs.claude.com