新手上路（三）：Claude Code Skills 装了一堆没用？20+ 个 Skill 横向对比 + 三套组合方案，按需抄

用户28717638795202026-05-02 18:11

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 命令（推荐）

powershell 复制代码 
# 在 Claude Code 交互会话内执行
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

方式二：npx skills add 命令

powershell 复制代码 
# 在终端直接执行
npx skills add OthmanAdi/planning-with-files -g
npx skills add vercel-labs/skills@find-skills -g

方式三：手动克隆

powershell 复制代码 
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 提取文字/表格、合并拆分、填写表单 需处理 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 pdf（官方） --- ✅ 与其他文档 Skill 共存
代码审查 内置 /review Superpowers requesting-code-review ✅ 可共存
元技能 skill-creator（内置） find-skills ✅ 可共存

四、纵向对比：Skills 如何串成工作流

单个 Skill 解决单一问题，纵向串起来才形成完整的工程能力。以下展示两条经过社区验证的纵向工作流。

4.1 完整开发流水线：从需求到交付的 7 阶段

text 复制代码 
用户需求
  │
  ▼
┌─────────────────────────────────────────────────┐
│ 阶段 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                               │
└─────────────────────────────────────────────────┘

这个流水线的关键设计原则：

  1. 硬门控（HARD GATE）：不是"建议不要跳过规划"，而是"规划未完成 → 执行 Skill 拒绝激活"。Superpowers 的每个阶段都有明确的进入条件和终端态。

  2. 文件系统作为内存 ：planning-with-files 的三文件模式确保------

    • /clear 后自动恢复进度
    • 50 次工具调用后不会漂移目标
    • 所有错误记录在案，不会重复踩坑

  3. 上下文隔离 ：subagent-driven-development 的每个任务在独立子 Agent 中执行，主会话只接收摘要。这解决了长任务的上下文污染问题。

4.2 文档输出流水线：研究 → 起草 → 统一 → 导出

text 复制代码 
研究主题
  │
  ▼
┌──────────────────────────────────┐
│ 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 开发环境：

text 复制代码 
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 敏感

powershell 复制代码 
# 在 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 元数据）

适合：日常做开发、希望有方法论约束但不至于太重

powershell 复制代码 
# 在 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 元数据）

适合：全职开发、团队协作、追求最高工程质量

powershell 复制代码 
# 终端安装
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 安装后不生效

报错日志

bash 复制代码 
安装了 skill-creator，但在会话中输入 /skill-creator 显示 Unknown command
或者安装了 planning-with-files，但 Claude 不会自动读取 task_plan.md

根因

Skill 目录结构错误是最常见原因。Claude Code 在启动时扫描 ~/.claude/skills/ 的子目录，寻找 SKILL.md 文件。如果：

  1. SKILL.md 不在 Skill 目录的根层级（比如被多套了一层文件夹）
  2. YAML frontmatter 格式错误（--- 分隔符缺失或语法错误）
  3. description 字段为空或过于模糊（Claude 无法匹配触发条件）
  4. 手动克隆时目录名带了 -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 也找不到

代码修复

检查一：确认目录结构

powershell 复制代码 
# 列出 skills 目录结构
Get-ChildItem -Recurse -Depth 2 $env:USERPROFILE\.claude\skills\

正确的输出应类似：

objectivec 复制代码 
C:\Users\<用户名>\.claude\skills\
├── planning-with-files\
│   └── SKILL.md
├── skill-creator\
│   └── SKILL.md

检查二：确认 YAML frontmatter

powershell 复制代码 
# 查看 SKILL.md 的前 10 行
Get-Content $env:USERPROFILE\.claude\skills\planning-with-files\SKILL.md -Head 10

应包含有效的 YAML frontmatter：

yaml 复制代码 
---
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 后缀：

powershell 复制代码 
Rename-Item $env:USERPROFILE\.claude\skills\planning-with-files-main $env:USERPROFILE\.claude\skills\planning-with-files

验证

重启 Claude Code 后：

bash 复制代码 
/help

在命令列表中应看到已安装的 Skill 名称（标注为 "(user)"）。输入一段与 Skill 描述匹配的任务描述，Claude 应自动激活对应 Skill。

七、Debug #2 --- 装了太多 Skills 导致上下文爆满

报错日志

bash 复制代码 
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

powershell 复制代码 
# 统计 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

powershell 复制代码 
# 删除不需要的 Skill 目录即可
Remove-Item -Recurse $env:USERPROFILE\.claude\skills\<skill-name>

第三步：在 CLAUDE.md 中声明 Skill 加载策略

在项目根目录 CLAUDE.md 中添加：

markdown 复制代码 
## Skills 管理
- 本项目主要使用以下 Skills: planning-with-files, frontend-design
- 对于简单任务（< 3 个文件的修改），不要激活 Superpowers 流程
- 文档类 Skill（docx/pptx/xlsx/pdf）仅在用户明确要求输出时激活

验证

bash 复制代码 
/context

查看上下文使用情况。在安装了 5-8 个 Skill 后，Layer 1 元数据应 < 3,000 tokens，实际编码可用上下文 > 70%。

八、Debug #3 --- 国内网络环境 Skill 安装失败

报错日志

powershell 复制代码 
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

或：

powershell 复制代码 
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。在国内网络环境下：

  1. registry.npmjs.org 直连超时
  2. 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 镜像 + 手动安装（推荐，无需代理）

powershell 复制代码 
# 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

powershell 复制代码 
# 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

验证

powershell 复制代码 
Get-ChildItem -Recurse -Depth 1 $env:USERPROFILE\.claude\skills\ | Select-Object Name
# 应看到已安装的 Skill 目录名

九、Debug #4 --- Skill 功能与内置指令冲突

报错日志

shell 复制代码 
# 安装了 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 中添加：

yaml 复制代码 
---
name: requesting-code-review
description: ...
disable-model-invocation: true
---

这样 Claude 不会自动激活该 Skill，只有你手动输入 /requesting-code-review 时才会触发。

方式二：设置 user-invocable: false

yaml 复制代码 
---
name: requesting-code-review
description: ...
user-invocable: false
---

相反：Claude 可以自动激活，但你手动输入时不会触发。

方式三：在 CLAUDE.md 中声明偏好

markdown 复制代码 
## Skill 偏好
- 代码审查优先使用内置 /review 命令
- 仅在完整执行 Superpowers 流水线时使用 requesting-code-review

验证

bash 复制代码 
/review

确认触发的是你预期的那个审查行为。

十、日常维护

10.1 启停命令

Skill 的生命周期管理就是目录管理：

powershell 复制代码 
# 临时禁用某个 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

powershell 复制代码 
# 通过 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 状态

powershell 复制代码 
# 统计安装的 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 官方
pdf 文档 /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 纵向流水线速记

text 复制代码 
需求 → 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](#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 为更明确的触发条件 "#%E5%85%ADdebug-1--skill-%E5%AE%89%E8%A3%85%E5%90%8E%E4%B8%8D%E7%94%9F%E6%95%88")
Claude 回复变短、质量下降 上下文被过多 Skill 元数据占用 审计并卸载不用的 Skill → [Debug #2](#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 为更明确的触发条件 "#%E4%B8%83debug-2--%E8%A3%85%E4%BA%86%E5%A4%AA%E5%A4%9A-skills-%E5%AF%BC%E8%87%B4%E4%B8%8A%E4%B8%8B%E6%96%87%E7%88%86%E6%BB%A1")
npm ERR! ETIMEDOUT npm 直连超时（国内网络） 配置镜像 + GitHub 镜像克隆 → [Debug #3](#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 为更明确的触发条件 "#%E5%85%ABdebug-3--%E5%9B%BD%E5%86%85%E7%BD%91%E7%BB%9C%E7%8E%AF%E5%A2%83-skill-%E5%AE%89%E8%A3%85%E5%A4%B1%E8%B4%A5")
Skill 覆盖了内置命令 Skill 与内置指令命名冲突 设置 disable-model-invocation: true → [Debug #4](#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 为更明确的触发条件 "#%E4%B9%9Ddebug-4--skill-%E5%8A%9F%E8%83%BD%E4%B8%8E%E5%86%85%E7%BD%AE%E6%8C%87%E4%BB%A4%E5%86%B2%E7%AA%81")
安装后重启仍不可见 Claude Code 未重新扫描 Skills 目录 完全退出后重新运行 claude
多个 Skill 同时激活行为异常 description 过于宽泛 优化 description 为更明确的触发条件

参考文献

  1. Equipping agents for the real world with Agent Skills --- Anthropic 官方博客
  2. Extend Claude with skills --- Claude Code 官方文档
  3. Anthropic 官方 Skills GitHub 仓库
  4. Superpowers: Transform Claude Code Into a Disciplined Development Workflow Engine
  5. planning-with-files --- GitHub 仓库
  6. Claude Code Skills Marketplace --- Ultimate Guide (Skywork)
  7. Best Claude Code Skills & Plugins 2026 Guide
  8. 给 Claude Code 装上「方法论」：深入解读 Superpowers --- 知乎
  9. Claude Code 进阶指南：10大必装技能与配置策略 --- 什么值得买
  10. Claude Code 必装 Skills 完全指南
  11. 30 Best Claude Code Skills to Add (by Use Case) --- FelloAI
  12. Claude Code Skills Tutorial: How to Create Custom Slash Commands --- Supalaunch
  13. 拒绝屎山代码！Superpowers 全局规划与规范执行能力 --- 火山引擎开发者
  14. Claude Code Skills Explained: Build Your First Real-World Automation --- TechGig
  15. Claude Code skill-creator 深度解析 --- CSDN
相关推荐
雨中飘荡的记忆3 小时前
玩转Claude Code：这个开源项目让我生产力翻倍的秘诀
claude
Joseph Cooper4 小时前
AI Agent 落地入门：从模型、工具到 Skills 与 MCP 的分工
人工智能·ai·agent·claude·skill·mcp
javaTodo9 小时前
Codex CLI 深度指南：安装配置、安全模型与 20+ 高手技巧
claude
小蠢驴打代码9 小时前
我做了一个工具：一键同步 Claude Code、Cursor、Codex 的 MCP 和 Skills 配置
openai·claude·cursor
javaTodo9 小时前
国内使用Claude Code集成VS Codo小白一站式教程
claude
NikoAI编程9 小时前
用AI不等于AI First：国内企业 AI 编程落地的第一站，是混乱
aigc·ai编程·claude
一条小鲤鱼9 小时前
Claude Code 使用指南（一）
claude
Resistance丶未来11 小时前
Kimi K2.6 智能应用场景与落地指南
人工智能·gpt·大模型·api·claude·kimi·kimi k2.6
程序新视界11 小时前
Claude Code的Skills实践及利器推荐：工欲善其事，必先利其器
claude
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03裂开！ChatGPT 居然开始要手机号验证，附详细解决方法04【AI】2026 年具身智能模型和世界模型总结05Codex 接入 DeepSeek API 完整配置文档062026年4月AI大事件深度解读：大模型竞争进入“深水区“07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08零基础教你claude code 接入 deepseek V409在Windows 11上安装Docker的踩坑记录102026年AI前瞻：量子AI、具身智能与科学发现的新纪元