反模式与坑
社区在这两年里踩出来的坑，集中收录在这里。每条都有具体错例与修法，按出现频率从高到低排序。
#1 description 讲了过程
症状：Skill 被触发了，但 agent 用粗糙的方式自己做完了任务，没有按 SKILL.md 正文里的 SOP 执行。
原因：description 把"怎么做"已经讲清了，agent 觉得不读正文也行。
坏例：
description: >
审查代码改动，按 logic / style / security / coverage 四个维度分别走一遍，
对每条问题生成 conventional comment 格式的反馈，最后输出 markdown 报告。好例：
description: >
Use when reviewing code changes, pull requests, or diffs.
Handles multi-pass review with security, style, and test coverage checks.#2 同目录放 README.md
症状：skill 目录下既有 SKILL.md 又有 README.md，agent 行为变得不可预测。
原因：Anthropic 官方明确要求"所有面向 AI 的文档都在 SKILL.md 或 references/ 里"。同目录 README 会让 agent 困惑哪份是真相。
坏例：
my-skill/
├── README.md ❌
├── SKILL.md
└── scripts/好例：
my-skill/
├── SKILL.md ← 唯一面向 AI 的入口
├── references/
│ └── usage.md ← 详细文档放这
└── scripts/如果一定要给人类读者写说明（例如分发到 GitHub），把 README.md 放在仓库根而不是 skill 目录内。
#3 Windows 反斜杠路径
症状：本地写脚本调用没问题，部署到 Linux/macOS 直接报错。
原因：agent 通常运行在 Linux 容器，反斜杠不被识别为路径分隔符。
坏例：
执行 scripts\helper.py ❌
读取 references\guide.md ❌好例：
执行 scripts/helper.py ✅
读取 references/guide.md ✅TIP
即使你的开发环境是 Windows，路径写法也要 Unix 风格。Windows 自己也支持正斜杠，跨平台兼容性最高。
#4 给 agent 太多选项
症状：agent 在多个备选方案之间反复横跳，结果输出不稳定。
原因：description 或 SOP 里写了「option A 或 option B」，agent 没有明确决策依据。
坏例：
## 第 3 步：生成报告
可以用以下任一方式：
- **方式 A**：调用 `scripts/markdown.py` 生成 Markdown
- **方式 B**：调用 `scripts/pdf.py` 生成 PDF
- **方式 C**：直接在对话里返回 HTML
根据情况自行选择。好例（用 Conditional Workflow Pattern）：
## 第 3 步：生成报告
判断输出格式：
- 用户**明确说**「PDF」/「打印」/「正式报告」 → 调用 `scripts/pdf.py`
- 用户**明确说**「网页」/「在线」 → 直接返回 HTML
- **其它默认情况** → 调用 `scripts/markdown.py`（Markdown 是最通用的中间格式）TIP
如果场景真的需要让用户选择，让 agent 主动询问（"您希望输出 PDF 还是 Markdown？"），而不是让它自己赌。
#5 假设包/工具已安装
症状：脚本在你机器上跑没问题，到 agent 那里报 ModuleNotFoundError。
原因：agent 运行环境是干净容器，没装你本地的依赖。
坏例：
直接调用 `from pypdf import PdfReader` 处理。好例：
## 前置依赖
\`\`\`bash
pip install pypdf
\`\`\`
确认安装后再使用：
\`\`\`python
from pypdf import PdfReader
\`\`\`IMPORTANT
即使是 Python 标准库以外的常见包（如 requests、pandas），也要在 SKILL.md 里显式声明依赖。
#6 引用 MCP 工具不带 server 前缀
症状：在多 MCP 服务器并存的环境，工具调用报 "tool not found"。
原因：MCP 工具名按 ServerName:tool_name 全限定命名，省略前缀会冲突。
坏例：
使用 `bigquery_schema` 拉取表结构。
使用 `create_issue` 创建 Jira 工单。好例：
使用 `BigQuery:bigquery_schema` 拉取表结构。
使用 `Jira:create_issue` 创建 Jira 工单。#7 时间敏感信息混在主流程里
症状：Skill 在某段时间后失效，agent 仍在使用过期的 API / endpoint / 字段。
原因：SKILL.md 主体里写了「截至 2026 年 5 月，X API 的 endpoint 是 ...」之类的时效信息。
坏例：
## 第 2 步：调用 API
POST https://api.example.com/v3/users （v3 是当前版本，2025-08 以后才上线）好例：
## 第 2 步：调用 API
POST {API_BASE}/users （endpoint 见 references/api-endpoints.md）
## 历史信息（仅供回滚参考）
> [!NOTE]
>
> 如果遇到旧版 v2 endpoint，注意 ...把所有时效信息外移到 references/ 或单独的"old patterns"段落，让主流程描述保持稳定。
#8 Frontmatter 的 description 超长
症状：Skill 元数据被截断，agent 看到的不完整。
原因：description 超过 1024 字符上限。
修法：
- 只保留触发条件（一两句话）
- 任何"做什么 / 怎么做"全部移到 SKILL.md 正文
- 触发关键词可以列表化但要克制，10 个以内为好
#9 SKILL.md 正文超过 500 行 / 5,000 token
症状：Skill 加载后剩余上下文窗口被吃光，agent 无法处理实际任务。
原因：把所有内容（参考文档、长示例、API schema）都塞进 SKILL.md 主体。
修法：
my-skill/
├── SKILL.md ← 只保留每次都需要的核心 SOP
├── references/
│ ├── api-schema.md ← 详细 schema 按需读取
│ └── edge-cases.md ← 罕见边界场景
└── assets/
└── report.template.md ← 长输出模板并在 SKILL.md 中明确告知何时读：
当响应非 200 状态码时，读取
references/api-errors.md。 不要泛泛指向 references/，要明确何时读哪份。
#10 description 中包含 claude / anthropic
症状：Skill 被部分平台拒绝加载。
原因：Anthropic 把这两个词作为保留字防止 prompt injection。
修法：用其它名字，例如 ai-helper、agent-router。
检查清单
发布 Skill 前，跑一遍 checklist：
元数据
- [ ]
name≤ 64 字符，kebab-case，与目录名一致 - [ ]
name不含claude/anthropic保留词 - [ ]
description≤ 1024 字符，只说触发不说过程 - [ ]
description含至少 3 个触发关键词 + 1 个隐式触发场景
内容
- [ ] SKILL.md < 500 行 / < 5,000 token
- [ ] 同目录内没有
README.md - [ ] 路径全部用正斜杠
/ - [ ] 引用其它文件只一层深（
scripts/x.py✅，scripts/sub/x.py⚠️） - [ ] 时效信息外移到 references/ 或独立段落
- [ ] 多 MCP 时工具名用全限定
ServerName:tool_name - [ ] 第三方依赖显式声明
pip install xxx
代码与脚本
- [ ] 脚本真的解决问题，不只是回调 Claude（"Solve, don't punt"）
- [ ] 脚本有清晰的错误处理与帮助输出
- [ ] 没有"voodoo constants"——所有硬编码值都有注释说明
测试
- [ ] 至少 3 条真实 query 隔离测试通过
- [ ] 在 Haiku / Sonnet / Opus（或你的目标模型）上分别跑过
- [ ] 与团队成员对评 description 与 SOP
下一步
避开了所有反模式，下一步：