06-Skills 下篇：设计原则与生态深度 —— 从会用会写到会设计

Skills 下篇：设计原则与生态深度 ------ 从会用会写到会设计

中篇你写出了第一个 Skill。下篇我们拔高一层------什么样的 Skill 才是好 Skill？为什么有些 Skill 装了就离不开，有些用一次就扔？以及，Skills 和 MCP 的边界在哪里，什么时候该用哪个？

Skill 设计五原则

这五条原则来自对社区 200+ Skill 的质量分析。好的 Skill 几乎都满足这五条，差的 Skill 往往违反其中几条。

原则一：单一职责

复制代码

一个 Skill 只做一件事，把它做到极致。

✅ 好的拆分：
  code-review       → 只做代码审查
  security-scan     → 只做安全检查
  deploy            → 只做部署

❌ 坏的合并：
  code-quality-all  → 审查 + 格式化 + 测试 + 部署
  → 什么都能做，什么都做不精
  → Checklist 太长，AI 的注意力被稀释
  → 改其中一个功能要动整个 Skill

判断标准：你能用一句话说清这个 Skill 做什么吗？如果需要"和"来连接，考虑拆分。

原则二：自包含

复制代码

Skill 应该在没有外部依赖的情况下也能工作。
如果有依赖，要在 metadata 里显式声明。

✅ 自包含：
  - 所有规则写在 SKILL.md 和 references/ 里
  - 不依赖特定的 MCP Server 才能运行
  - 如果有推荐搭配的 MCP Server，放在 "建议搭配" 而非 "必须依赖"

❌ 隐式依赖：
  SKILL.md 里写："使用 context7 查询最新文档"
  → 用户没装 context7 MCP，Skill 就废了一半
  → 但 metadata 里 dependencies 是空的

原则三：可组合

复制代码

好的 Skill 像乐高积木，可以互相调用、自由组合。

示例：deploy Skill 调用 code-review Skill

# SKILL.md of deploy
## 部署前检查
- [ ] 运行 /review（调用 code-review Skill）
- [ ] 运行测试套件
- [ ] 检查环境变量是否完整

## 部署步骤
...

组合的价值在于：你不用写一个"万能 Skill"，而是用 5 个小 Skill 拼出任何工作流。

复制代码

/review + /test + /deploy = 标准发布流程
/review + /security-scan = 安全审计流程
/prd-to-tasks + /review + /deploy = 完整需求交付流程

原则四：渐进披露

复制代码

不要把所有内容塞进 SKILL.md。用三级结构控制 Token 开销。

SKILL.md（总是加载）
  → 核心指令 + Checklist + 输出格式
  → 控制在 2000 字以内

references/（按需加载）
  → 详细规则、背景知识、边界情况
  → 每个文件聚焦一个主题

外部链接（AI 自行获取）
  → 官方文档、API 参考
  → 只在真正需要时给链接

判断标准：如果你的 SKILL.md 超过 3000 字，几乎一定违反了渐进披露。立刻拆分。

原则五：失败可预期

复制代码

Skill 执行失败时，AI 的行为必须是可预期的------不能"静默继续"。

✅ 好的失败处理：
  # SKILL.md
  ## 错误处理
  - 如果安全检查无法完成（如缺少必需的 MCP Server），
    必须明确告知用户："⚠️ 无法完成安全检查：缺少 security-scanner MCP Server"
  - 不要静默跳过检查项

❌ 坏的失败处理：
  没有错误处理指令
  → AI 可能自己决定"跳过"某些检查
  → 你以为审查过了，其实漏了关键项

核心原则 ：Skill 失败时 宁可报错，不要跳过。假的"通过"比真的"报错"危险一百倍。

Skill 的四种反模式

以下是社区 Skill 中最常见的设计错误。

反模式一：过度抽象

复制代码

❌ 反例：
  创建一个 "quality-gate" Skill，试图同时做：
  - 代码审查
  - 安全扫描
  - 测试运行
  - 覆盖率检查
  - 依赖审计

  结果：SKILL.md 5000 字，AI 每次只能覆盖其中 2-3 项，
  不漏项全靠运气。

✅ 正例：
  拆成 5 个独立 Skill，用 deploy Skill 串联：
  /security-scan → /dependency-audit → /test → /review → 合并

反模式二：隐含假设

复制代码

❌ 反例：
  # SKILL.md
  "用 Black 格式化代码"
  → 假设用户装了 Black，且配置了正确的 line-length
  → 如果用户用的是 Ruff，这条指令不仅无效，还会造成混乱

✅ 正例：
  # SKILL.md
  "用项目配置的格式化工具格式化代码（检查 pyproject.toml
   或 .prettierrc 确定使用哪个工具和什么配置）"
  → 不假设具体工具，让 AI 读配置文件来确定

隐含假设是最常见的 Skill Bug。写完 Skill 后让一个同事试试------他碰到的问题就是你隐含假设的地方。

反模式三：硬编码路径

复制代码

❌ 反例：
  "将所有 Skill 放在 ~/.claude/skills/ 目录"
  → 假设用户是 macOS/Linux
  → Windows 用户的路径完全不同
  → 即使是 macOS，有些公司用自定义的 CLAUDE_HOME

✅ 正例：
  "将 Skill 放在 Claude Code 的 skills 目录下
  （运行 `claude config dir` 查看具体路径）"
  → 平台无关，让用户自己查

反模式四：缺少 trigger 说明

复制代码

❌ 反例：
  metadata.yml 里只有：
    description: "代码审查工具"
  → 太短，AI 无法判断什么时候该触发

✅ 正例：
  metadata.yml 里写：
    description: >
      标准化代码审查。当用户要求"review"、"审查"、"检查代码"、
      "帮我看下这段代码"时触发。也支持 /review 和 /cr 命令。
  → 明确的触发场景 + 关键词 + 命令

一个测试方法：在 Claude Code 里用 5 种不同的表达方式描述同一个需求，看 Skill 是否每次都能触发。少触发一次，就补充一个关键词。

Skill vs MCP：边界与协同

这是最常被问到的问题：什么时候用 Skill，什么时候用 MCP Server？

核心区别

复制代码

Skill                              MCP Server
─────                              ──────────
本质：一段提示词                      本质：一个服务进程
做的事：引导 AI 怎么想                做的事：给 AI 工具/数据
不提供新功能                         提供新功能（Tool/Resource/Prompt）
用 Markdown 写                       用 Python/Node/任何语言写
不需要运行                           需要运行（进程或远程服务）
Token 开销：低（只加载提示词）         Token 开销：中（Tool 描述占用上下文）

边界判断框架

复制代码

你需要的是什么？
  │
  ├─ 给 AI 一套思维框架/工作流程
  │   → 用 Skill
  │   例：code-review 的检查清单、deploy 的步骤、onboarding 的知识
  │
  ├─ 给 AI 访问外部数据/系统的能力
  │   → 用 MCP Server
  │   例：查 GitHub Issues、操作数据库、调用公司内部 API
  │
  ├─ 两者都需要？
  │   → Skill + MCP 协同
  │   例：deploy Skill 调用 GitHub MCP 创建 Release
  │       review Skill 调用 Context7 MCP 查最新安全公告
  │
  └─ 不确定？
      → 先用 Skill（开发成本低、Token 省）。不够用了再加 MCP。

协同模式：Skill 调用 MCP Tool

这是最强大的组合------Skill 提供流程，MCP 提供能力。

复制代码

┌─────────────────────────────────────────────┐
│  Skill: deploy                              │
│                                             │
│  部署流程：                                  │
│  1. 运行 /review（另一个 Skill）              │
│  2. 运行测试                                 │
│  3. 调用 GitHub MCP → 创建 Release           │  ← Skill 调用 MCP
│  4. 调用 Slack MCP → 发送部署通知            │  ← Skill 调用 MCP
│  5. 调用 Playwright MCP → 验证线上页面       │  ← Skill 调用 MCP
│                                             │
└─────────────────────────────────────────────┘

协同的最佳实践：

Skill 里只写"调用 GitHub MCP 创建 Release"，不写具体怎么调
MCP Server 里定义具体的 Tool 和调用方式
换 MCP Server 时，Skill 不需要改（解耦）
如果 MCP Server 挂了，Skill 其他步骤还能继续（容错）

什么时候该把 Skill "升级"为 MCP Server

复制代码

Skill 就够了                                     该升级为 MCP Server 了
────────────                                     ────────────────────
AI 本身就能完成（代码审查、写文档）                 需要外部数据（查数据库、调 API）
用 AI 的推理能力就够了                             需要执行计算（跑测试、构建镜像）
固定的流程，不需要动态数据                         需要访问私有系统（公司内部的 CI/CD）

Skill Marketplace 深度探索

分类体系

Claude Code 的 Skill Marketplace 按以下分类组织：

复制代码

语言/框架类
├── python-best-practices
├── react-patterns
├── go-error-handling
└── rust-ownership-guide

工作流类
├── code-review
├── test-gen
├── deploy
├── refactor
└── debug

安全类
├── security-scan
├── dependency-audit
├── secret-detector
└── owasp-checklist

知识传授类
├── onboarding
├── api-design-guide
├── architecture-review
└── style-guide

质量评估标准

Marketplace 里的 Skill 良莠不齐。用这套标准快速评估：

评估维度	看什么	🟢 好	🔴 差
活跃度	最近更新时间	3 个月内	超过 1 年
成熟度	版本号	1.0 以上	0.0.x
文档	README 清晰度	有使用示例 + 配置说明	只有一句话描述
反馈	Issues/PR 处理	有响应	无人维护
依赖	外部依赖数量	0-1 个	3+ 个必需依赖

一个小技巧：打开 Skill 的 SKILL.md 文件，直接看 Checklist。如果 Checklist 写得好（具体、可判断、分级），这个 Skill 大概率靠谱。如果 Checklist 写的是一堆抽象原则，别装。

Star/Fork 数据的正确读法

复制代码

Star 高 ≠ 好 Skill

常见误导：
- "10K Star 的 Skill 一定比 100 Star 的好"
  → Star 多可能是因为它是最早的，不一定是最好的
  → 100 Star 的新 Skill 可能质量更高，只是还没被发现

正确用法：
- Fork 数 > Star 数  → 用户在使用和定制，好信号
- Issue 关闭率 > 80% → 维护者活跃，好信号
- 近期有 commit       → 没被废弃，好信号
- Star 增长趋势       → 看趋势不看绝对值

团队 Skill 管理

当团队开始重度使用 Claude Code 时，Skill 管理会成为一个新挑战。

阶段一：每个人自己装（2-5 人团队）

复制代码

开发 A: ~/.claude/skills/ 装了 6 个 Skill
开发 B: ~/.claude/skills/ 装了 8 个 Skill（其中 3 个和 A 重叠但版本不同）
开发 C: 没装任何 Skill，每次手写提示词

问题：A 和 B 的 Code Review 标准不一样。C 的效率明显低。

阶段二：项目级 Skill 仓库（5-20 人团队）

复制代码

项目仓库/
├── .claude/
│   └── skills/           ← 项目级 Skill，随项目版本管理
│       ├── code-review/
│       ├── deploy/
│       └── security-scan/
├── CLAUDE.md             ← 引用项目 Skill
└── AGENTS.md

变化：

团队共用一套 Skill，标准统一
Skill 的版本随项目一起管理（Git）
新人 clone 项目后自动获得全套 Skill
更新 Skill 需要 PR Review，质量有保障

阶段三：内部 Plugin（20+ 人团队）

把整套路（Skills + MCP + Hooks + Agents 配置）打包成内部 Plugin：

复制代码

company-coding-plugin/
├── plugin.json
├── skills/
│   ├── code-review/
│   ├── deploy/
│   ├── security-scan/
│   └── api-design/
├── hooks/
│   └── pre-commit-security-check.sh
└── .mcp.json

团队成员只需要：

bash 复制代码

claude plugin install @company/coding-plugin

一条命令装上所有配置。Plugin 的详细开发见第 9-10 篇。

团队 Skill 的版本管理

复制代码

版本策略（参考 semver）：
  ├─ 1.0.0 → 1.0.1：修 bug，不改变行为
  ├─ 1.0.0 → 1.1.0：新增检查项，向后兼容
  └─ 1.0.0 → 2.0.0：改变检查标准，不向后兼容

变更流程：
  修改 Skill → 提 PR → Review（至少一人） → 合并
  → 更新 CHANGELOG → 通知团队

Skills 三部曲总结

复制代码

上篇（第 4 篇）：用别人的 Skill
  → 了解 Skill 是什么、四种触发方式、三种安装方式
  → 10 个必装 Skill 推荐 + 如何判断 Skill 是否适合自己
  → 三级渐进加载原理

中篇（第 5 篇）：写自己的 Skill
  → 什么时候该写、目录结构逐行拆解
  → Checklist 驱动 vs 散文驱动
  → 手把手实战 + 调试三招

下篇（本篇）：设计好的 Skill
  → 五条设计原则 + 四种反模式
  → Skill vs MCP 边界与协同
  → Marketplace 探索 + 团队管理

读完这三篇，你应该能从"会用别人的 Skill"到"能写出让全团队都离不开的 Skill"。

06-Skills 下篇：设计原则与生态深度 —— 从会用会写到会设计

Skills 下篇：设计原则与生态深度 ------ 从会用会写到会设计

Skill 设计五原则

原则一：单一职责

原则二：自包含

原则三：可组合

原则四：渐进披露

原则五：失败可预期

Skill 的四种反模式

反模式一：过度抽象

反模式二：隐含假设

反模式三：硬编码路径

反模式四：缺少 trigger 说明

Skill vs MCP：边界与协同

核心区别

边界判断框架

协同模式：Skill 调用 MCP Tool

什么时候该把 Skill "升级"为 MCP Server

Skill Marketplace 深度探索

分类体系

质量评估标准

Star/Fork 数据的正确读法

团队 Skill 管理

阶段一：每个人自己装（2-5 人团队）

阶段二：项目级 Skill 仓库（5-20 人团队）

阶段三：内部 Plugin（20+ 人团队）

团队 Skill 的版本管理

Skills 三部曲总结

延伸阅读