第十一章 避坑指南

你将学到

• 8 大新手最容易踩的"功能型"坑及解法。
• Skill 不被触发时的 10 步系统排查。
• Token 成本失控的 5 种典型场景与应对。
• 4 种模型（Claude 4.5/4/Haiku、外部模型）的选型矩阵。
• 30+ 条常见报错对照表。

你需要准备

• 一杯咖啡。这一章信息密度最大，慢慢看。
• 已经踩过若干坑的你（没踩过也没事，提前预防）。

一、8 大新手坑

坑 1：description 写得像"自我介绍"，不像"触发器"

❌ 反例：

description: This is a great helper for managing your weekly schedule. It is very useful and can do many things.

读起来像 LinkedIn 简介。Claude 看不出该什么时候召唤它。

✅ 正例：

description: >
  Build / update / query a personal weekly schedule. Show this week's todos,
  conflicts, free slots. Trigger keywords: "本周日程""周计划""schedule""日历整理"
  "this week's plan""帮我看一下这周".

心法：description 写给 AI 看，不是给老板看。重在"什么时候用"，不在"我多牛"。

坑 2：把 Prompt 当 Skill

很多新手写 Skill：

---
name: writing-helper
description: Help me write better articles.
---

请写一篇 2000 字的关于 xxx 的文章，要求：
1. 有标题
2. 三段论
3. 文笔好

这是 Prompt 模板，不是 Skill。Skill 应该是有触发场景 + 有可复用流程 + 适合多次召唤的复合体。

✅ 区分原则：

• 写一次用一次 → Prompt 模板
• 写一次用 100 次 + 每次输入不同 → Skill

坑 3：Skill 太多互相打架

你装了 10 个 Skill，里面 3 个都跟"周报"沾边：

• weekly-report（公司四段）
• weekly-summary（个人复盘）
• friday-recap（周五汇总）

你说"帮我写周报"——Claude 不知道选哪个，要么乱选，要么三个都召唤，结果一团糟。

✅ 解法：

• 同一类 Skill 只留 1 个。
• 实在要保留多个，让 description 明确各自专属场景：
  • weekly-report: 公司汇报
  • weekly-summary: 个人记录
  • friday-recap: 团队 standup
• 或者把它们合并成 1 个带分支的 Skill。

坑 4：在 SKILL.md 里塞示例数据

❌ 反例：

## 工作流
1. 拉 Notion 数据，比如：
   - 任务 A: 完成
   - 任务 B: 进行中
   - 任务 C: 暂停
2. ...

这种"示例"会让 Claude 以为这就是真实数据，输出周报时把"任务 A B C"写进去，闹笑话。

✅ 解法：

把示例放在专门的"示例"段落里，明确说"以下仅为格式参考，不是真实数据"：

## 工作流
1. 拉 Notion 数据。
2. ...

## 输出格式参考（不要使用以下内容，仅展示结构）
| 任务 | 状态 |
| --- | --- |
| <task> | <status> |

坑 5：忘记 allowed-tools，安全裸奔

写 Skill 时图省事，从来不写 allowed-tools，结果 Skill 默认拥有所有工具权限。

如果你写的 Skill 准备分享出去，没有 allowed-tools 限制 = 给别人一把万能钥匙。

✅ 习惯：每写 Skill 第一件事，写 allowed-tools。哪怕是 Read, Write, Bash 这种相对宽的，也比不写强。

坑 6：盲目相信 Claude 的"判断"

新手常以为 Skill 一启动就万事大吉。实际上：

• Claude 仍可能跑歪（特别是含开放性创作的 Skill）。
• 脚本可能因为数据格式异常报错。
• 输出质量取决于模型，不是 Skill。

✅ 习惯：

1. 关键 Skill 跑完后，人工 spot check 至少 3 个数据点。
2. 第一次跑新 Skill 用小样本（10 行 vs 1000 行）。
3. 重要任务永远 review 一遍再发出去。

坑 7：把 Skill 写成"小说"

我见过 SKILL.md 长达 3 万字的——把所有可能场景、所有边界、所有思考都塞进去。

后果：

• token 成本飙升（远超过 5k 的建议上限）。
• Claude 注意力被稀释，反而漏读关键指令。
• 维护痛苦。

✅ 解法：

1. SKILL.md 主体控制在 2000 中文字以内。
2. 详细的"领域知识"放 references/。
3. 详细的"代码逻辑"放 scripts/。
4. 详细的"格式样例"放 templates/。

坑 8：装完 Skill 不测试就上生产

你装了一个"销售提案 PPT 一键出"Skill，第一次跑就用真客户数据。结果 PPT 上把客户名字打错、报价多了一个 0、把竞品的功能写成了自家的。

发出去之后……

✅ 解法：

任何 Skill 第一次跑都用 fake 数据：

• 客户名用 "TestCo Inc."
• 数字用整数（10000、50000、80000）
• 联系人用 "John Doe"

跑通格式 → 调样式 → 再用真数据。

二、Skill 不被触发的 10 步排查

按从简单到复杂的顺序排查：

第 1 步：Skill 是否启用

• 网页版/Desktop：Settings → Skills → 确认开关开了。
• Code：ls ~/.claude/skills/<your-skill>/SKILL.md 确认文件存在。

第 2 步：Skill 列表里有没有它

让 Claude 自己说：

请列出当前你能识别的所有 Skill，包含 name 和 description 摘要。

如果你的不在里头：

• 文件夹名是 kebab-case 吗？
• SKILL.md 文件名拼写完全正确？（大小写敏感）
• 文件夹层级对吗？是 ~/.claude/skills/<name>/SKILL.md，不是 ~/.claude/skills/SKILL.md。

第 3 步：YAML frontmatter 格式对吗

把 SKILL.md 的 frontmatter 部分复制到 https://yamlvalidator.com 验证。

常见错误：

• name:weekly-report（冒号后没空格）
• name: weekly report（name 含空格）
• 缩进用了 tab 而不是空格
• 冒号后用了中文标点

第 4 步：description 有没有触发关键词

打开你刚才说的话，逐字对照 description。

你说："帮我写一下本周的工作总结"
description 含: ["weekly", "report", "周报"]

→ 没有任何关键词命中，所以不触发。

解法: 在 description 里加 "工作总结"、"本周总结"、"weekly summary"。

第 5 步：description 是否被其它 Skill"压过"

某些通用 Skill（如官方的 docx）可能命中你的提示词。Claude 的偏好是：

• 优先选 description 与提示词重合度最高的。
• 优先选 instructions 更具体的。
• 优先选官方 Skill（少数情况下）。

可以在你的 Skill description 里加一句"专门处理 X，不处理通用 Y"——明确边界。

第 6 步：Skill 是否被禁用

检查 SKILL.md frontmatter 有没有：

disable-model-invocation: true

如果有，你的 Skill 只能通过 /skill-name 手动调用，不会被自动召唤。删除这一行。

第 7 步：环境变量 / 配置错误

如果 Skill 依赖的环境变量没设（如 NOTION_TOKEN），Skill 可能在启动时报错并退出，看起来像"没被触发"。

检查 Claude 的输出末尾或日志。

第 8 步：模型版本兼容性

某些 Skill 可能对模型版本有要求。如果你用的是 Claude 3.5（旧版），可能不支持新版的某些字段。

升级到 Claude 4.5 或更新。

第 9 步：上下文窗口已满

如果你在一个超长对话里跑（已经几十万 token），Claude 可能因为上下文压力跳过 Skill 加载。

开新对话。

第 10 步：终极方案——直接召唤

如果以上 9 步都不行，明确告诉 Claude：

请使用 weekly-report skill 帮我写本周周报。

强制召唤是 debug 利器。如果连强制都不响应，问题大概率出在 1–3 步。

三、Token 成本失控 5 种场景

Claude 按 token 计费。Skill 用得不当会让账单飙升。5 种典型场景：

场景 1：装了 50 个 Skill 全开

每个 Skill 的 metadata 占约 100 token。50 个 = 5000 token，每次对话都要加载。

如果你每天对话 100 次，一个月就是 100 × 30 × 5000 = 1500 万 token，仅用于"识别 Skill"——一分都没有用在干活上。

解法：定期审计，关掉不用的。

场景 2：references 文件过大

你在 references/ 下塞了一份 10 万字的"公司全部产品介绍"。Skill 召唤时 Claude 一次性读完——单次 25 万 token 直接爆表。

解法：

• 把 references 拆小（按主题、按部门）。
• SKILL.md instructions 里明确告诉 Claude "只读 references/<具体文件>，不要读全部"。

场景 3：Skill 反复重新读取同一文件

Skill 写得不好，每一步都"读一遍 references/all-products.md"——读 10 次 = 10 倍 token。

解法：在 instructions 里写"将 references/xxx.md 一次性加载到上下文，后续步骤复用"。

场景 4：长任务没有分批

你让 Skill 处理 10 万行 Excel，单次完成。结果 Claude 把整张表都加载到上下文里。

解法：

• 在 SKILL.md 里加"超过 1000 行的数据，分批处理（每批 500 行）"。
• 或用 Python 脚本预处理，只把汇总结果给 Claude 看。

场景 5：模型选错

用 Claude 4.5（最贵的）跑"统计字数"这种小任务，单次成本 0.10 美元。如果跑 100 次/天，一个月 300 美元。

解法：见下一节"模型选型矩阵"。

四、模型选型矩阵

按 2026 年 4 月 Anthropic 最新发布：

价格随时变化，以 Anthropic 官网 为准。

在 SKILL.md 里指定模型

---
name: word-counter
description: ...
model: claude-haiku-4    # 简单任务用最便宜的
---

选型决策树

任务复杂度 + 预算
├── 高复杂 + 预算充足  → claude-4.7-opus（医疗/法律咨询）
├── 中复杂 + 通用       → claude-4.5-sonnet（默认推荐）
├── 简单 + 高频         → claude-haiku-4（字数统计、分类）
└── 重要决策            → claude-4.7-opus + 让用户确认

混合策略（高级玩法）

一个 Skill 用多个模型：

• 第 1 步（数据预处理）：claude-haiku-4
• 第 2 步（核心分析）：claude-4.5-sonnet
• 第 3 步（最终决策）：claude-4.7-opus

通过子 agent / 嵌套 Skill 实现。第九章讲过基础。

五、常见报错对照表

安装/启用类

触发类

执行类

数据类

沙箱限制类

网络类

六、Token 成本管理实操

6.1 监控当前使用量

• Anthropic Console: https://console.anthropic.com/settings/billing 看实时账单。
• Claude Code: 跑 claude usage 查最近用量。
• 在 Skill 里加日志: 每次调用前后记录 token 消耗。

6.2 设置预算告警

Anthropic Console 支持设月度预算上限和告警邮件。强烈建议设上限——避免某个 Skill bug 一夜烧光你的额度。

6.3 优化 SKILL.md 的"瘦身"清单

• description ≤ 350 字
• 主体 ≤ 2000 字
• 重复指令合并
• 示例放专门段落
• 大数据放 references/，按需读
• 简单任务用 Haiku 模型

6.4 一个真实成本对比

某用户每天用 Skill 跑：

• 50 次 Excel 处理（4.5 Sonnet）：约 $1.5/天
• 200 次邮件分类（Haiku）：约 $0.2/天
• 5 次 PPT 生成（4.5 Sonnet）：约 $0.5/天

合计：约 $2.2/天 × 30 = $66/月。

如果 PPT 生成误用 4.7 Opus：5 × 5 × 30 = $750/月——75 倍差距。

模型选型不是小事。

七、写 Skill 的"反模式"清单

把这些反着做就能避免大部分坑：

八、给爸妈用的 Skill 的额外注意

第六章我们讲过给爸妈做 Skill 的方法。这里补充几个"避坑细则"：

1. 输出极简：爸妈要的是清单/答案本身，不是 "Powered by Claude" 这种花哨提示。
2. 错误处理友好：不要让他们看到 KeyError: 'name' 这种报错——用 try/except 包裹，给"试试再发一遍"。
3. 不要让他们改任何配置：所有需要"输入 token""勾选选项"的步骤替他们做掉。
4. 加二次确认：涉及"扣钱""发邮件给陌生人"等动作，必须让他们看到"确认要执行吗？"。
5. 保留撤销能力：能做 ctrl+Z 的就别做不可逆的。

九、本章一图回顾

+-------------------------------------------------------------+
|                  Skill 避坑全景                              |
+-------------------------------------------------------------+
| 8 大新手坑                                                   |
|  1. description 像自我介绍   2. Prompt 当 Skill              |
|  3. Skill 互相打架            4. 塞示例数据                  |
|  5. 忘 allowed-tools          6. 盲信 AI 判断                |
|  7. 写成 3 万字小说           8. 不测试就上生产              |
+-------------------------------------------------------------+
| Skill 不被触发 10 步排查                                     |
|  启用 → 列表 → YAML → 关键词 → 冲突 → 禁用 →                 |
|  环境变量 → 模型版本 → 上下文 → 强制召唤                     |
+-------------------------------------------------------------+
| Token 成本失控 5 场景                                        |
|  Skill 太多 / references 太大 / 反复读 /                    |
|  长任务不分批 / 模型选错                                     |
+-------------------------------------------------------------+
| 模型选型                                                     |
|  4.7 Opus  → 医疗/法律, 复杂决策                            |
|  4.5 Sonnet → 日常主力 (90% 场景)                           |
|  Haiku 4   → 高频简单                                        |
+-------------------------------------------------------------+
| 报错对照表 30+ 条                                            |
|  分类: 安装/触发/执行/数据/沙箱/网络                         |
+-------------------------------------------------------------+

给你 3 句话提醒

1. 90% 的"Skill 没用"问题，根因是 description 写不好。改 description 永远是第一选择。
2. 账单失控比"Skill 不工作"更可怕——前者悄无声息，后者立竿见影。每月查一次账单。
3. 给爸妈做的 Skill 必须测试 5 遍以上。他们对错误的容忍度是程序员的 1/100。

下一章预告

下一章 第十二章 从用户到创造者，我们走最后一段——从"会用 Skill 的人"变成"造 Skill 的人"。

我会带你完成一个完整的发布流程：把你的 Skill 推到 GitHub、写一份让人愿意装的 README、加入 PolySkill / 5tldr 这些社区市场、5 种把 Skill 变成副业的路径、长期成长的 4 条原则。

走，进最后一章。