5.2 七种反模式——别这样写技能包
📋 多工具适用说明
本节的反模式是通用概念，适用于所有 AI 编程工具：
- 太长、太模糊、过度授权、过度自动触发——所有工具的常见错误
- 示例以 Claude Code 语法展示，但问题本质是通用的
引言
小王写了一个 200 行的技能包，涵盖代码审查的所有维度：安全性、性能、可维护性、测试覆盖……他觉得写得很全面。
结果：AI 加载这个技能包后表现反而变差了——它开始在不相关的问题上浪费 token，审查结果越来越泛泛。
写得多的技能包不如写得好的技能包。 以下是七种最常见的错误写法。
反模式一：技能包太长
症状：主文件超过 200 行（警告线），或超过 500 行（硬上限）
为什么有害：技能包加载后内容留在上下文中，每行都是持续的 token 开销。自动压缩后只保留前 5000 token。
反面示例：一个 190 行的"代码解释"技能包，16 个章节，6 种语言的考虑
行数标准：
- 推荐：50-150 行（甜蜜区）
- 警告线：200 行（超过就该拆分）
- 硬上限：500 行（可接受但需重构）
正确做法：拆分为多个小技能包，详细内容移到辅助文件（Claude Code 用 references/）
反模式二：流程性指令放在项目指令文件
症状：项目指令文件里有"部署步骤"、"审查清单"等流程内容
为什么有害：项目指令文件每次会话、每轮请求都加载。偶尔才用的流程在 90% 的时间里浪费 token
判断标准：如果项目指令文件的某段从"是什么"变成了"怎么做"，就是技能包的信号
正确做法：项目指令文件保持 200 行以内，流程内容移到技能包
反模式三：过度使用动态注入
症状：一个技能包用了 4+ 个 !command``
为什么有害：每个命令在调用时执行，增加延迟。大输出消耗 token
正确做法：只在 Claude 绝对需要实时数据时使用。能让 Claude 按需读取的文件，不要预处理注入
反模式四：技能包太通用
症状：description: "全面的代码质量审查"，内容适用于任何项目
为什么有害：通用技能包缺乏项目特定上下文，给 AI 没有护栏。而且通用技能包通常太长（见反模式一）
反面示例：
description: 全面的代码质量审查
# 30 行通用建议，任何项目都适用 = 任何项目都不够好正面示例（React 的 /verify）：
description: 提交前验证变更
# 精确的 yarn 命令、明确的项目约定正确做法：技能包应该特定于你的项目——引用精确命令、文件路径和约定
反模式五：描述太模糊
症状：description: "帮助审查代码"
为什么有害：AI 用 description 判断何时自动触发（Claude Code 和 Windsurf 有此机制，Cursor 需手动触发）。模糊 = 不触发 = 技能包等于不存在
改进对比：
| 描述 | 效果 |
|---|---|
| "帮助审查代码" | Claude 不确定何时用，很少触发 |
| "审查 PR 的代码质量、安全性和性能。当说'审查'、'review'、'帮我看看这个 PR'时使用" | 精准匹配 |
正确做法：前置关键用例，包含触发短语，可以"pushy"一点
反模式六：有副作用的技能包缺少手动控制（Claude Code 示例）
症状：部署技能包没有 disable-model-invocation: true
为什么有害：Claude 可能觉得"代码看起来准备好了"就自动部署
正确做法：deploy、commit、send-message 等有副作用的技能包必须设 disable-model-invocation: true（Claude Code），其他工具确保关键操作需用户确认
反模式七：指南型技能包使用隔离执行（Claude Code 示例）
症状：
name: api-conventions
context: fork
agent: Explore
---
使用 REST API 时遵循以下约定……为什么有害：fork 的子代理需要可执行的任务。只给指南没有任务，子代理返回空结果
正确做法：指南型技能包用 inline 模式（默认），或设 user-invocable: false 让 Claude 自动加载为背景知识
反模式速查
| 反模式 | 核心问题 | 一句话修复 |
|---|---|---|
| 技能包太长 | Token 浪费 + 遵从度下降 | 拆分 + 移到辅助文件 |
| 流程在项目指令文件 | 全量加载不经济 | 提取为技能包 |
| 过度注入 | 延迟 + Token 浪费 | 只注入必需数据 |
| 技能包太通用 | 无护栏 + 通常太长 | 写项目特定的技能包 |
| 描述太模糊 | 等于不存在 | 加触发短语 |
| 副作用无保护 | 自动部署风险 | 加手动控制机制 |
| 指南用隔离执行 | 子代理返回空 | 用 inline 或 user-invocable: false |
本节小结
📌 本节核心要点
- 七种反模式都比"不会写"更危险——因为看起来"写对了"
- 核心原则：简洁 > 全面、特定 > 通用、明确 > 模糊
- 最致命的反模式：有副作用技能包没有手动控制
- 最常见的反模式：技能包太长和描述太模糊
思考题
- 检查你写过的技能包，有没有踩中这些反模式？最常见的是哪个？
- "技能包太通用"和"技能包太长"经常一起出现，为什么？
- 你怎么判断一个技能包是"太通用"还是"恰好足够通用"（比如可以在多个项目中复用）？
下一节预告
理论够了，看真实项目怎么做的。下一节深入React、Anthropic 和 llm-wiki 三个项目的技能包设计——从他们的成功和失败中学习。