Windows 10 · Claude Code CLI v2.x · 2026-05-01
一、这篇教程解决什么问题
一句话定位：Skill是什么？刚完成 Claude Code 安装和 /init 项目初始化后，面对上百个可选 Skills 不知道该装哪个、装了不知道怎么串起来用。
Claude Code Skills 生态已有 800K+ 可选项，但大多数人装了一堆却没用起来。 本文做两件事：
✅ 横向（同类 Skill 怎么选）：8 类 20+ 个 Skills 的功能边界、优劣对比、选型决策树
✅ 纵向（多个 Skills 如何串成工作流）：Superpowers 7 阶段硬门控开发流水线 + 文档输出流水线，完整串联
阅读前提：
- 已完成 Claude Code CLI 安装，
claude --version正常输出版本号 - 已完成
/init项目初始化，项目根目录存在CLAUDE.md - 了解基本的斜杠命令用法（
/help、/config等）
读完能得到什么：
- 一张横向对比速查表：8 类共 20+ 个 Skills 的功能边界、优劣对比、选型决策树
- 两条经过社区验证的纵向工作流：Superpowers 七阶段硬门控开发流水线 + 文档输出流水线
- 三套推荐安装组合（最小/标准/全栈），每套给出精确的 token 开销和安装命令
- 4 个 Debug 场景（Skill 不生效、上下文爆满、版本冲突、国内网络安装失败）
二、Skills 基础概念速览
2.1 什么是 Skill
Skill（Agent Skill）是 Anthropic 于 2025 年 10 月 16 日正式发布的扩展机制。一个 Skill 就是一个包含 SKILL.md 指令文件的目录，放在特定位置后 Claude Code 自动发现并加载。
Skill 不是：
- ❌ 不是 MCP 服务器（MCP 提供外部工具连接，Skill 提供使用知识）
- ❌ 不是 Plugin（Plugin 是打包格式，Skill 是内容本身）
- ❌ 不是普通的 slash command（slash command 需要手动输入，Skill 可以自动激活）
2.2 Skill vs 其他扩展机制对比
| 机制 | 触发方式 | 用途 | 文件位置 |
|---|---|---|---|
| Skill | 自动匹配 + 手动 / 调用 | 教授 Claude "怎么做" | ~/.claude/skills/ 或 .claude/skills/ |
| Slash Command（旧） | 仅手动 / 调用 | 快捷执行固定提示词 | .claude/commands/ |
| MCP Server | 自动加载工具列表 | 连接外部系统（数据库、API） | ~/.claude.json 中配置 |
| Hook | 事件触发（PreToolUse 等） | 自动化确定性操作 | .claude/hooks/ |
| CLAUDE.md | 会话启动时自动加载 | 持久项目上下文 | 项目根目录 |
2.3 三层渐进式加载机制
Skill 的核心设计是渐进式加载（Progressive Disclosure），这是能同时安装上百个 Skill 而不爆上下文的关键：
| 层级 | 加载内容 | 加载时机 | Token 开销 |
|---|---|---|---|
| Layer 1 | YAML 元数据（name + description） | 会话启动时加载所有已安装 Skill | ~100 tokens / 个 |
| Layer 2 | 完整 SKILL.md 正文 | 当 Claude 判定 Skill 与当前任务匹配时 | 通常 < 5,000 tokens |
| Layer 3 | 附带脚本/模板/参考文档 | 当 SKILL.md 显式引用时 | 按需，用完即释放 |
这意味着你可以安装 50 个 Skill，启动时仅消耗 ~5,000 tokens 的元数据，实际工作时只有 1-3 个 Skill 被完整加载。
2.4 安装方式
Claude Code 支持两种安装途径：
方式一：/plugin 命令（推荐）
# 在 Claude Code 交互会话内执行
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
方式二：npx skills add 命令
# 在终端直接执行
npx skills add OthmanAdi/planning-with-files -g
npx skills add vercel-labs/skills@find-skills -g
方式三：手动克隆
git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\skills\planning-with-files
方式四：CC Switch导入
方式三需要手动处理 Skill 依赖关系。方式一和方式二会自动处理。
三、横向对比：同类 Skills 怎么选
按功能域将主流 Skills 分为 8 类，每类做横向对比。相同功能域的 Skill 通常只选一个，避免指令冲突。
3.1 【规划类】 Skills — 选一个
| 维度 | Superpowers (writing-plans) | planning-with-files | 内置 /plan |
|---|---|---|---|
| 作者 | Jesse Vincent (obra) | OthmanAdi | Anthropic 官方内置 |
| 安装量 | ~170K GitHub stars | ~17.6K GitHub stars | 内置，零安装 |
| 核心思路 | 硬门控流程：禁止跳过规划直接写代码 | Manus 式三文件持久化规划 | 先出方案再动手 |
| 输出物 | docs/superpowers/specs/ 下的设计文档 | task_plan.md + findings.md + progress.md | 无持久文件 |
| 跨会话恢复 | ✅ 通过 git 提交的设计文档 | ✅ 三文件存磁盘，Hook 自动重读 | ❌ 会话关闭即丢失 |
| 上下文开销 | ~800 tokens（仅 writing-plans） | ~300 tokens | ~0 tokens（内置命令） |
| 学习曲线 | 中等（14 个 Skill 的完整方法论） | 低（开箱即用） | 极低 |
| 适用场景 | 中大型项目、团队协作、需要方法论约束 | 所有项目、跨会话长任务 | 简单任务、快速方案确认 |
| 不足 | Token 开销大（全套装完后 ~2,500 tokens 元数据）；方法论强制性强，小任务显得笨重 | 无方法论引导，只提供文件框架 | 无持久化、无流程约束 |
选型建议：
- 只用内置
/plan：适合单次会话的简单任务 - 加装
planning-with-files：需要跨会话记忆，但不需要改变工作习惯 - 加装
Superpowers：愿意接受完整方法论约束，追求工程质量
3.2 【开发流程类】Skills — 选 Superpowers 还是零散组合
| 维度 | Superpowers（全套 14 个 Skills） | 零散 Skill 组合 |
|---|---|---|
| 覆盖阶段 | 头脑风暴 → 规划 → 执行 → TDD → 审查 → 调试 → 交付 | 按需拼装，可能遗漏阶段 |
| 门控机制 | 硬门控（HARD GATE）：每个阶段有明确的进入/退出条件，不可跳过 | 无门控，靠使用者自觉 |
| TDD 强制 | 铁律：测试未写之前写的代码全部删除 | 取决于是否单独安装测试类 Skill |
| 代码审查 | 两阶段审查（规格合规 + 代码质量），用独立子 Agent | 需额外安装 review 类 Skill |
| 调试方法论 | 4 阶段根因分析，3 次失败即质疑架构 | 依赖 Claude 内置调试能力 |
| 并行执行 | dispatching-parallel-agents：3 个以上独立失败才停止 | 需手动用 /agents 管理 |
| Token 开销 | ~2,500 tokens 元数据（14 个 Skills 各 ~180 tokens） | 按需，通常 ~500-1,500 tokens |
| 适用场景 | 严肃工程项目、团队协作、希望 AI 像高级工程师一样工作 | 个人项目、快速原型、不想被约束 |
Superpowers 的 14 个 Skill 清单与功能：
| 阶段 | Skill 名称 | 功能 |
|---|---|---|
| 设计 | brainstorming | 苏格拉底式问答，梳理需求与方案 |
| 规划 | writing-plans | 生成颗粒度 2-5 分钟的任务计划 |
| 环境 | using-git-worktrees | 隔离工作空间，并行分支开发 |
| 执行 | subagent-driven-development | 每个任务独立子 Agent + 两阶段审查 |
| 执行 | executing-plans | 批量执行任务计划，支持检查点 |
| 执行 | dispatching-parallel-agents | 并行调度多个子 Agent |
| 质量 | test-driven-development | RED-GREEN-REFACTOR 铁律 |
| 质量 | requesting-code-review | 规格合规 + 代码质量双维度审查 |
| 质量 | receiving-code-review | 结构化处理审查反馈 |
| 调试 | systematic-debugging | 4 阶段根因分析 |
| 调试 | verification-before-completion | "没有证据的完成是欺骗" |
| 交付 | finishing-a-development-branch | 4 种分支收尾选项 |
| 元技能 | writing-skills | 用 TDD 方式编写 Skill 本身 |
| 元技能 | using-superpowers | 1% 规则：自动触发方法论约束 |
3.3 【设计类】Skills — 选一个主设计 Skill
| 维度 | frontend-design（Anthropic 官方） | brand-guidelines（Anthropic 官方） | canvas-design（Anthropic 官方） |
|---|---|---|---|
| 定位 | 前端 UI 设计，消除"AI 风格" | 品牌视觉统一 | 视觉设计输出 PNG/PDF |
| 激活方式 | UI 任务自动激活 | 品牌相关任务自动激活 | 视觉设计任务手动调用 |
| 硬性禁止 | Inter/Roboto/Arial 字体、紫色渐变、白色卡片 | 无硬性禁止 | 无硬性禁止 |
| 美学指导 | 独特字体、主导色+锐利强调色、高冲击力动效、非对称构图 | 按品牌手册强制执行 | 自由创作 |
| 输出格式 | React/Vue/HTML 组件代码 | 品牌色彩+字体规范 | PNG/PDF 静态设计稿 |
| 适用场景 | Web 前端开发 | 企业汇报/对外文档 | 宣传图/海报/插画 |
选型建议：
- 做 Web 前端 →
frontend-design（必装） - 做企业 PPT/文档 →
brand-guidelines+pptx - 做视觉创意 →
canvas-design - 三者不冲突，可同时安装。
frontend-design和brand-guidelines的触发域不同，会自动匹配。
3.4 【文档类】 Skills — 按需装，不冲突
Anthropic 官方提供了 4 个文档处理 Skill，全部来自 document-skills 包：
| Skill | 功能 | 适用人群 | Token 开销 |
|---|---|---|---|
| docx | 创建/编辑 Word 文档（样式、表格、批注、多节） | 需输出正式文档者 | ~1,200 tokens |
| pptx | 创建 PPT（从大纲或要点生成） | 需做汇报者 | ~1,500 tokens |
| xlsx | 创建 Excel（公式、图表、数据清洗） | 需处理数据表格者 | ~1,800 tokens |
| 提取文字/表格、合并拆分、填写表单 | 需处理 PDF 者 | ~900 tokens |
四个文档 Skill 不互斥，可以全装。它们使用独立的文件格式库，不会在内存中冲突。但注意：全装后 Layer 1 元数据约 400 tokens。
3.5 【代码审查类】 Skills — 内置 vs 社区
| 维度 | 内置 /review | Superpowers requesting-code-review | security-review（内置） |
|---|---|---|---|
| 触发 | 手动 /review | Superpowers 流程自动触发 | 手动 /security-review |
| 审查维度 | git diff 变更概览 | 规格合规 + 代码质量双维度 | 安全漏洞扫描 |
| 审查者 | 当前会话的 Claude | 独立子 Agent（隔离上下文） | 当前会话的 Claude |
| 输出 | 行内评论 | 结构化审查报告 | 安全漏洞报告 |
3.6 【元技能类】 — 管理和创建 Skills
| 维度 | skill-creator（Anthropic 官方） | find-skills（Vercel 社区） |
|---|---|---|
| 功能 | 创建和优化自定义 Skill | 搜索生态系统中 800K+ Skills |
| 核心工作流 | 定义测试用例 → A/B 对比 → 评分 → 迭代优化 | 关键词搜索 → 相关性排序 → 安装 |
| 适用场景 | 把重复性任务沉淀为 Skill | 不知道有没有现成的 Skill |
| 内置 | ✅ /skill-creator 内置，零安装 | ❌ 需要安装 |
| 安装命令 | 无需安装，直接输入 /skill-creator | npx skills add vercel-labs/skills@find-skills -g |
3.7 横向对比总表
| 功能域 | 首选 | 备选 | 能否共存 |
|---|---|---|---|
| 规划 | planning-with-files（轻量） 或 Superpowers（重量） | 内置 /plan | planning-with-files + Superpowers 可共存 |
| 开发流程 | Superpowers（完整方法论） | 零散组合 | 不要同时用两套流程 |
| 前端设计 | frontend-design（官方） | brand-guidelines | ✅ 可共存，触发域不同 |
| Word 文档 | docx（官方） | — | ✅ 与其他文档 Skill 共存 |
| PPT | pptx（官方） | — | ✅ 与其他文档 Skill 共存 |
| Excel | xlsx（官方） | — | ✅ 与其他文档 Skill 共存 |
| pdf（官方） | — | ✅ 与其他文档 Skill 共存 | |
| 代码审查 | 内置 /review | Superpowers requesting-code-review | ✅ 可共存 |
| 元技能 | skill-creator（内置） | find-skills | ✅ 可共存 |
四、纵向对比：Skills 如何串成工作流
单个 Skill 解决单一问题，纵向串起来才形成完整的工程能力。以下展示两条经过社区验证的纵向工作流。
4.1 完整开发流水线：从需求到交付的 7 阶段
用户需求
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 1: 头脑风暴 (Superpowers: brainstorming) │
│ • 苏格拉底式一问一答，梳理需求、约束、方案 │
│ • 硬门控: 方案未确认前禁止写任何代码 │
│ • 产出: 设计文档，git 提交到 docs/superpowers/specs/ │
│ • 终端态: 明确调用 writing-plans，不调用其他 Skill │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 2: 规划 (Superpowers: writing-plans │
│ + planning-with-files 3 文件模式) │
│ • 创建 task_plan.md / findings.md / progress.md │
│ • 每个任务 2-5 分钟颗粒度，含确切文件路径 │
│ • 硬门控: 禁止 TODO/TBD/占位符 │
│ • Hook 机制: PreToolUse 前自动重读计划 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 3: 执行 (Superpowers: executing-plans │
│ + subagent-driven-development) │
│ • 每个任务启动独立子 Agent（上下文隔离） │
│ • 两阶段审查: 规格合规 → 代码质量 │
│ • 可并行调度 3+ 个子 Agent (dispatching-parallel) │
│ • 支持检查点: 完成一个任务 → 提交 → 继续 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 4: TDD (Superpowers: test-driven-development)│
│ • 铁律: 测试之前写的代码 → 存在且失败 → 删除 │
│ • RED → GREEN → REFACTOR 循环 │
│ • 反理性化表: 驳斥每一个跳过测试的借口 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 5: UI 实现 (frontend-design 自动激活) │
│ • 仅在涉及 UI 代码时触发 │
│ • 先做设计方向（目的/调性/约束/差异化）再写代码 │
│ • 禁止 Inter/Roboto/紫色渐变 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 6: 验证 (Superpowers: verification-before- │
│ completion + systematic-debugging) │
│ • "声称完成但没有证据 = 欺骗，不是效率" │
│ • 必须: 运行 → 读取 → 验证 → 陈述 │
│ • 调试: 4 阶段根因分析，3 次失败 → 停止， │
│ 质疑架构级问题 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 阶段 7: 交付 (Superpowers: finishing-a- │
│ development-branch) │
│ • 4 种选项: merge / PR / keep / discard │
│ • 所有测试必须通过才提供 merge 选项 │
│ • 自动清理 worktree │
└─────────────────────────────────────────────────┘
这个流水线的关键设计原则：
-
硬门控（HARD GATE）：不是"建议不要跳过规划"，而是"规划未完成 → 执行 Skill 拒绝激活"。Superpowers 的每个阶段都有明确的进入条件和终端态。
-
文件系统作为内存：
planning-with-files的三文件模式确保——/clear后自动恢复进度- 50 次工具调用后不会漂移目标
- 所有错误记录在案，不会重复踩坑
-
上下文隔离：
subagent-driven-development的每个任务在独立子 Agent 中执行，主会话只接收摘要。这解决了长任务的上下文污染问题。
4.2 文档输出流水线：研究 → 起草 → 统一 → 导出
研究主题
│
▼
┌──────────────────────────────────┐
│ Step 1: 深度研究 │
│ Skill: in-depth-research │
│ 产出: 结构化研究发现 + 来源列表 │
│ 文件: findings.md │
└────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Step 2: 内容起草 │
│ Skill: internal-comms │
│ (Anthropic 官方，周报/FAQ/邮件模板) │
│ 产出: 结构化内容大纲 + 正文初稿 │
└────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Step 3: 品牌统一 │
│ Skill: brand-guidelines │
│ (Anthropic 官方) │
│ 产出: 配色/字体统一后的终稿 │
└────────────┬─────────────────────┘
│
▼
┌──────────────────────────────────┐
│ Step 4: 格式导出 │
│ Skill: docx / pptx / pdf │
│ 产出: 正式文档文件 │
└──────────────────────────────────┘
4.3 同域 Skills 的协同规则
多个 Skills 同时安装时，遵循以下协同规则：
| 规则 | 说明 | 示例 |
|---|---|---|
| 触发域分离 | 不同 Skill 的 description 字段描述不同触发场景，Claude 自动匹配 | frontend-design（UI 任务触发）和 brand-guidelines（品牌任务触发）不会同时激活 |
| 显式链接 | Skill A 的 SKILL.md 中明确写"终端态是调用 Skill B" | Superpowers 的 brainstorming 结束时必须调用 writing-plans，禁止调用 frontend-design |
| 优先级覆盖 | 同名 Skill，项目级覆盖用户级 | .claude/skills/review/SKILL.md 优先于 ~/.claude/skills/review/SKILL.md |
| 上下文隔离 | 使用 context: fork 的 Skill 在独立子 Agent 中运行，不污染主会话 | /audit 可以同时 fork 安全审查、性能审查、风格审查三个子 Agent |
4.4 进阶：Skills + MCP + Hooks 全栈组合
Skills 不只是独立工作。与 MCP 和 Hooks 组合后形成完整的 AI 开发环境：
CLAUDE.md → 始终在线的项目约定（"使用 pnpm"、"提交前运行测试"）
.claude/rules/ → 路径域规则（按语言/目录定制行为）
Skills → 按需激活的工作流和参考知识
MCP Servers → 外部工具/数据连接（数据库、GitHub API、Slack）
Hooks → 确定性自动化（每次编辑后运行 ESLint）
Subagents → 隔离工作者，处理上下文重的子任务
Plugins → 打包以上所有组件的分发层
实际协同示例：一个 MCP 服务器连接你的 PostgreSQL 数据库；一个 Skill 记录你的表结构、查询规范和数据分析模式；一个 Hook 在每次数据库迁移后自动运行完整性检查。
五、推荐安装组合
5.1 最小组合（3 个 Skill，~500 tokens 元数据）
适合：刚上手、不想改变工作习惯、对 token 敏感
# 在 Claude Code 交互会话中执行
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
# 在终端手动安装
git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\skills\planning-with-files
| Skill | 用途 | Token 开销 |
|---|---|---|
内置 /skill-creator | 零安装，把重复操作沉淀为 Skill | 0 |
planning-with-files | 跨会话任务记忆 | ~300 tokens |
docx | 输出正式 Word 文档 | ~200 tokens 元数据 |
5.2 标准开发组合（5 个 Skill，~1,200 tokens 元数据）
适合：日常做开发、希望有方法论约束但不至于太重
# 在 Claude Code 交互会话中执行
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
# 在终端安装
npx skills add OthmanAdi/planning-with-files -g
npx skills add obra/superpowers -g
| Skill | 用途 | Token 开销 |
|---|---|---|
planning-with-files | 持久化任务规划 | ~300 tokens |
Superpowers (全套) | 完整开发方法论 | ~2,500 tokens 元数据 |
frontend-design | 前端 UI 质量（Anthropic 官方内置） | ~150 tokens 元数据 |
docx | Word 文档输出 | ~200 tokens 元数据 |
内置 /skill-creator | 创建自定义 Skill | 0 |
5.3 全栈组合（8 个 Skill，~3,000 tokens 元数据）
适合：全职开发、团队协作、追求最高工程质量
# 终端安装
npx skills add OthmanAdi/planning-with-files -g
npx skills add obra/superpowers -g
npx skills add vercel-labs/skills@find-skills -g
# Claude Code 会话内安装
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills
| Skill | 用途 | Token 开销 |
|---|---|---|
Superpowers (全套 14 个) | 完整开发方法论，7 阶段流水线 | ~2,500 tokens |
planning-with-files | 三文件持久化规划 | ~300 tokens |
frontend-design | 前端设计质量 | ~150 tokens |
brand-guidelines | 品牌视觉统一 | ~200 tokens |
docx | Word 文档 | ~200 tokens |
pptx | PPT 演示 | ~250 tokens |
xlsx | Excel 表格 | ~300 tokens |
find-skills | 搜索 800K+ Skill 生态 | ~100 tokens |
六、Debug #1 — Skill 安装后不生效
报错日志
安装了 skill-creator，但在会话中输入 /skill-creator 显示 Unknown command
或者安装了 planning-with-files，但 Claude 不会自动读取 task_plan.md
根因
Skill 目录结构错误是最常见原因。Claude Code 在启动时扫描 ~/.claude/skills/ 的子目录，寻找 SKILL.md 文件。如果：
SKILL.md不在 Skill 目录的根层级（比如被多套了一层文件夹）- YAML frontmatter 格式错误（
---分隔符缺失或语法错误） description字段为空或过于模糊（Claude 无法匹配触发条件）- 手动克隆时目录名带了
-main后缀（GitHub 的默认分支名）
一览对比表
| 对比维度 | 正确结构 | 错误结构 |
|---|---|---|
| 目录层级 | skills/planning-with-files/SKILL.md | skills/planning-with-files/planning-with-files-main/SKILL.md |
| YAML frontmatter | ---\nname: xxx\ndescription: xxx\n--- | 缺少 --- 或 description 为空 |
| 文件名 | SKILL.md（大写） | skill.md / README.md |
| 触发测试 | 输入相关描述后 Skill 自动激活 | 手动 /skill-name 也找不到 |
代码修复
检查一：确认目录结构
# 列出 skills 目录结构
Get-ChildItem -Recurse -Depth 2 $env:USERPROFILE\.claude\skills\
正确的输出应类似：
C:\Users\<用户名>\.claude\skills\
├── planning-with-files\
│ └── SKILL.md
├── skill-creator\
│ └── SKILL.md
检查二：确认 YAML frontmatter
# 查看 SKILL.md 的前 10 行
Get-Content $env:USERPROFILE\.claude\skills\planning-with-files\SKILL.md -Head 10
应包含有效的 YAML frontmatter：
---
name: planning-with-files
description: Implements Manus-style persistent markdown planning for multi-session development. Use when starting complex tasks, multi-session work, or any task requiring persistent planning.
---
检查三：修正克隆目录名
如果 git clone 后目录名带了 -main 后缀：
Rename-Item $env:USERPROFILE\.claude\skills\planning-with-files-main $env:USERPROFILE\.claude\skills\planning-with-files
验证
重启 Claude Code 后：
/help
在命令列表中应看到已安装的 Skill 名称（标注为 "(user)"）。输入一段与 Skill 描述匹配的任务描述，Claude 应自动激活对应 Skill。
七、Debug #2 — 装了太多 Skills 导致上下文爆满
报错日志
Context window limit reached. Consider using /compact.
或者 Claude 回复明显变短、质量下降、忘记之前的对话内容
根因
虽然每个 Skill 的 Layer 1 元数据仅 ~100 tokens，但如果装了 50+ 个 Skill，元数据总量就是 5,000+ tokens。加上 CLAUDE.md、系统提示词、对话历史，实际留给编码任务的上下文可能只剩不到 50%。
更关键的是 Layer 2：如果多个 Skill 的 description 写得太宽泛（比如都写了 "Use when writing code"），Claude 可能同时激活 5-6 个 Skill，全部加载完整 SKILL.md 正文，瞬间消耗 20,000+ tokens。
一览对比表
| 对比维度 | 合理安装 | 过度安装 |
|---|---|---|
| Skill 数量 | 3-8 个 | 30-50 个 |
| Layer 1 元数据开销 | ~300-3,000 tokens | ~3,000-50,000 tokens |
| 同时激活的 Layer 2 Skill | 1-3 个 | 5-10 个 |
| 编码可用上下文 | > 70% | < 40% |
| Claude 表现 | 专注、准确 | 回复变短、忘记上下文、答非所问 |
代码修复
第一步：审计当前安装的 Skill
# 统计 Skill 数量
(Get-ChildItem -Directory $env:USERPROFILE\.claude\skills\).Count
(Get-ChildItem -Directory .\.claude\skills\ -ErrorAction SilentlyContinue).Count
# 列出所有 Skill 名称
Get-ChildItem -Directory $env:USERPROFILE\.claude\skills\ | Select-Object Name
第二步：清理不用的 Skill
# 删除不需要的 Skill 目录即可
Remove-Item -Recurse $env:USERPROFILE\.claude\skills\<skill-name>
第三步：在 CLAUDE.md 中声明 Skill 加载策略
在项目根目录 CLAUDE.md 中添加：
## Skills 管理
- 本项目主要使用以下 Skills: planning-with-files, frontend-design
- 对于简单任务（< 3 个文件的修改），不要激活 Superpowers 流程
- 文档类 Skill（docx/pptx/xlsx/pdf）仅在用户明确要求输出时激活
验证
/context
查看上下文使用情况。在安装了 5-8 个 Skill 后，Layer 1 元数据应 < 3,000 tokens，实际编码可用上下文 > 70%。
八、Debug #3 — 国内网络环境 Skill 安装失败
报错日志
PS> npx skills add OthmanAdi/planning-with-files -g
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/ failed
或：
PS> git clone https://github.com/OthmanAdi/planning-with-files.git
fatal: unable to access 'https://github.com/OthmanAdi/planning-with-files.git/':
Failed to connect to github.com port 443: Timed out
根因
npx skills add 底层依赖 npm registry 和 GitHub API。在国内网络环境下：
registry.npmjs.org直连超时github.com直连超时
如果已按《Claude Code 在 Windows & DeepseekV4Pro上的国内环境安装与调试指南》配置了 npm 淘宝镜像，npx 命令可正常执行——但 npx skills add 内部可能仍会访问 GitHub 下载 Skill 文件，这个步骤不走 npm registry。
一览对比表
| 对比维度 | npx skills add | 手动 git clone |
|---|---|---|
| npm 镜像支持 | ✅ 可走淘宝镜像 | N/A |
| GitHub 访问 | ❌ 需要直连 GitHub | ❌ 需要直连 GitHub |
| 代理支持 | ✅ 设置 http.proxy 后可用 | ✅ 设置 http.proxy 后可用 |
| GitHub 镜像 | ❌ 不支持 | ✅ 可替换域名为镜像 |
代码修复
方式一：配置 npm 镜像 + 手动安装（推荐，无需代理）
# 1. 确认 npm 镜像已配置
npm config get registry
# 应输出 https://registry.npmmirror.com/
# 2. 通过 GitHub 镜像克隆（替换 github.com 为镜像）
git clone https://hub.nuaa.cf/OthmanAdi/planning-with-files.git $env:USERPROFILE\.claude\skills\planning-with-files
# 3. 验证
Get-ChildItem $env:USERPROFILE\.claude\skills\planning-with-files\
方式二：配置代理后使用 npx
# 1. 设置 git 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
# 2. 设置 npm 代理
npm config set proxy http://127.0.0.1:7890
# 3. 执行安装
npx skills add OthmanAdi/planning-with-files -g
# 4. 使用完后清除代理（避免影响国内站点访问）
git config --global --unset http.proxy
git config --global --unset https.proxy
npm config delete proxy
验证
Get-ChildItem -Recurse -Depth 1 $env:USERPROFILE\.claude\skills\ | Select-Object Name
# 应看到已安装的 Skill 目录名
九、Debug #4 — Skill 功能与内置指令冲突
报错日志
# 安装了 Superpowers 后，输入 /review 没有触发内置的代码审查，而是触发了
Superpowers 的 requesting-code-review Skill，行为与预期不同
根因
当 Skill 名称与内置斜杠命令同名时，Skill 优先级高于内置命令。这是 Claude Code 的命名冲突解析机制：用户级 > 项目级 > 内置。
Superpowers 的 requesting-code-review 虽然全名不同，但它会在 description 中声明 "Use when the user asks for code review"，导致 Claude 在用户输入 /review 时匹配到 Superpowers 的 Skill 而非内置 /review。
一览对比表
| 对比维度 | 内置 /review | Superpowers requesting-code-review |
|---|---|---|
| 触发方式 | 手动 /review | 自动匹配 "review" 关键词 + 手动调用 |
| 审查深度 | git diff 变更概览 | 规格合规 + 代码质量双维度 |
| 子 Agent | 否（当前会话） | 是（隔离上下文） |
| Token 消耗 | 低 | 高（独立子 Agent + 完整审查指令） |
| 是否可禁用 | N/A | 可删除 Skill 目录 |
代码修复
有三种方式控制 Skill 的激活行为：
方式一：设置 disable-model-invocation: true（推荐）
编辑 Skill 的 SKILL.md 文件，在 frontmatter 中添加：
---
name: requesting-code-review
description: ...
disable-model-invocation: true
---
这样 Claude 不会自动激活该 Skill，只有你手动输入 /requesting-code-review 时才会触发。
方式二：设置 user-invocable: false
---
name: requesting-code-review
description: ...
user-invocable: false
---
相反：Claude 可以自动激活，但你手动输入时不会触发。
方式三：在 CLAUDE.md 中声明偏好
## Skill 偏好
- 代码审查优先使用内置 /review 命令
- 仅在完整执行 Superpowers 流水线时使用 requesting-code-review
验证
/review
确认触发的是你预期的那个审查行为。
十、日常维护
10.1 启停命令
Skill 的生命周期管理就是目录管理：
# 临时禁用某个 Skill（重命名目录）
Rename-Item $env:USERPROFILE\.claude\skills\superpowers $env:USERPROFILE\.claude\skills\superpowers.disabled
# 恢复启用
Rename-Item $env:USERPROFILE\.claude\skills\superpowers.disabled $env:USERPROFILE\.claude\skills\superpowers
# 卸载（永久删除）
Remove-Item -Recurse $env:USERPROFILE\.claude\skills\<skill-name>
10.2 更新 Skill
# 通过 git 管理的 Skill: cd 到目录后 git pull
cd $env:USERPROFILE\.claude\skills\planning-with-files
git pull
# 通过 npm 管理的 Skill
npx skills update OthmanAdi/planning-with-files -g
10.3 审计当前 Skill 状态
# 统计安装的 Skill
Get-ChildItem -Directory $env:USERPROFILE\.claude\skills\ | ForEach-Object {
$frontmatter = Get-Content "$($_.FullName)\SKILL.md" -Head 5 -ErrorAction SilentlyContinue
Write-Output "--- $($_.Name) ---"
Write-Output $frontmatter
Write-Output ""
}
# 估算元数据 token 开销（每个 Skill ~100 tokens）
$count = (Get-ChildItem -Directory $env:USERPROFILE\.claude\skills\).Count
Write-Output "总计: $count 个 Skills, 预估元数据开销: $($count * 100) tokens"
十一、速查卡
11.1 文件路径汇总
| 文件/目录 | 绝对路径 | 用途 |
|---|---|---|
| 用户级 Skills | C:\Users\<用户名>\.claude\skills\ | 个人所有项目可用 |
| 项目级 Skills | <项目>\.claude\skills\ | 团队共享 |
| Skill 定义文件 | <skill-dir>\SKILL.md | Skill 核心指令 |
| 内置 skill-creator | C:\Users\<用户名>\.claude\skills\skill-creator\ | 创建/优化 Skill |
| 企业托管策略 | C:\Program Files\ClaudeCode\managed-settings.json | IT 管理员下发 |
11.2 安装命令速查
| 安装方式 | 命令 | 适用场景 |
|---|---|---|
| Claude Code 会话内 | /plugin marketplace add anthropics/skills | 添加官方市场 |
| Claude Code 会话内 | /plugin install document-skills@anthropic-agent-skills | 安装官方文档 Skill |
| 终端 npx | npx skills add obra/superpowers -g | 安装社区 Skill（全局） |
| 终端 git 镜像 | git clone https://hub.nuaa.cf/<user>/<repo>.git $env:USERPROFILE\.claude\skills\<name> | 国内网络环境 |
| 内置 | /skill-creator（零安装） | 创建自定义 Skill |
11.3 推荐 Skill 横向对比速查表
| Skill | 类别 | 安装方式 | 元数据开销 | 适用场景 | 注意 |
|---|---|---|---|---|---|
| planning-with-files | 规划 | npx skills add | ~300 tokens | 跨会话长任务 | 与 Superpowers 可共存 |
| Superpowers | 开发流程 | npx skills add | ~2,500 tokens | 严肃工程、团队协作 | 全套 14 个 Skills；方法论强约束 |
| frontend-design | 设计 | 内置 | ~150 tokens | Web 前端 UI | 禁止 Inter/Roboto 字体 |
| brand-guidelines | 设计 | /plugin install | ~200 tokens | 企业汇报/品牌统一 | Anxthropic 官方 |
| docx | 文档 | /plugin install | ~200 tokens | Word 文档输出 | Anxthropic 官方 |
| pptx | 文档 | /plugin install | ~250 tokens | PPT 演示输出 | Anxthropic 官方 |
| xlsx | 文档 | /plugin install | ~300 tokens | Excel 表格输出 | Anxthropic 官方 |
| 文档 | /plugin install | ~150 tokens | PDF 处理 | Anxthropic 官方 | |
| find-skills | 元技能 | npx skills add | ~100 tokens | 搜索 Skill 生态 | Vercel 社区 |
| skill-creator | 元技能 | 内置 /skill-creator | 0 | 创建/优化 Skill | Anxthropic 官方 |
11.4 Skill 纵向流水线速记
需求 → brainstorming → writing-plans → executing-plans
├── subagent-driven-development
├── test-driven-development
├── frontend-design (UI 任务自动激活)
└── verification-before-completion
└── finishing-a-development-branch
11.5 常见报错 → 解决方案
| 报错特征 | 根因 | 解决 |
|---|---|---|
/skill-name 显示 Unknown command | 目录结构错误或 YAML frontmatter 缺失 | 检查 SKILL.md 位置与格式 → Debug #1 |
| Claude 回复变短、质量下降 | 上下文被过多 Skill 元数据占用 | 审计并卸载不用的 Skill → Debug #2 |
npm ERR! ETIMEDOUT | npm 直连超时（国内网络） | 配置镜像 + GitHub 镜像克隆 → Debug #3 |
| Skill 覆盖了内置命令 | Skill 与内置指令命名冲突 | 设置 disable-model-invocation: true → Debug #4 |
| 安装后重启仍不可见 | Claude Code 未重新扫描 Skills 目录 | 完全退出后重新运行 claude |
| 多个 Skill 同时激活行为异常 | description 过于宽泛 | 优化 description 为更明确的触发条件 |
参考文献
- Equipping agents for the real world with Agent Skills — Anthropic 官方博客
- Extend Claude with skills — Claude Code 官方文档
- Anthropic 官方 Skills GitHub 仓库
- Superpowers: Transform Claude Code Into a Disciplined Development Workflow Engine
- planning-with-files — GitHub 仓库
- Claude Code Skills Marketplace — Ultimate Guide (Skywork)
- Best Claude Code Skills & Plugins 2026 Guide
- 给 Claude Code 装上「方法论」：深入解读 Superpowers — 知乎
- Claude Code 进阶指南：10大必装技能与配置策略 — 什么值得买
- Claude Code 必装 Skills 完全指南
- 30 Best Claude Code Skills to Add (by Use Case) — FelloAI
- Claude Code Skills Tutorial: How to Create Custom Slash Commands — Supalaunch
- 拒绝屎山代码！Superpowers 全局规划与规范执行能力 — 火山引擎开发者
- Claude Code Skills Explained: Build Your First Real-World Automation — TechGig
- Claude Code skill-creator 深度解析 — CSDN
