Writing Skills — Skill & MCP 元技能

铁律：软硬同重

Skill 和 MCP 的质量 = 代码的质量。 写得烂的 skill/MCP description → 猫选错工具 → 用户体验差。 写 skill = 为未来的猫写路标；写 MCP description = 为模型写路由信号。两者都不是日记。

价值门禁：别教聪明猫写 for 循环

写 skill 前先判定：它是不是在给聪明 agent 复述训练集里已经很强的通用知识？

好 skill 不是教聪明猫写 for 循环；好 skill 是把领域 know-how、历史坑、证据标准、行为刹车放到猫会自然经过的位置。

必须至少命中一项，否则不要写成 skill：

更完整判据见 writing-skills/cat-cafe-skill-quality-principles.md。

开工前：先看范本再动手

不要凭空写。 先读一个同类型的好例子，理解家里的风格和标准。

写 MCP tool 前还要 grep 家里现有同类 tool 的 description，保持风格一致。

四份必读文档的 T0 精华

以下是核心原则。详细展开、案例拆解、模板见对应 ref 文件。

T0-0：Skill 价值门禁（Cat Café）

Skill 不是知识垃圾桶。写之前先选择正确载体：

T0-1：Description 是路由信号，不是摘要（Anthropic + 知识工程指南）

Description 决定猫"要不要触发"。三层加载机制：

1. 常驻层：猫只看到 name + description（所有 skill/tool 的元数据常驻 system prompt）
2. 加载层：被判定相关时，SKILL.md 正文才进入上下文
3. 按需层：refs/scripts/assets 再按需读取

description 写不好 = 正文永远进不了上下文 = "抽屉里没人翻的菜谱"

三件套格式（必须）: Use when ... / Not for ... / Output: ...

• 详见 writing-skills/anthropic-best-practices.md（Anthropic 原文）
• 详见 (internal reference removed) §1.4（进场门票机制）

T0-2：Gotchas 是最高价值内容（Anthropic）

Skill/MCP 里最值钱的不是流程描述，是 Common Mistakes / GOTCHA 段落。这是猫犯过的错的沉淀。

• 每个 skill 必须有 Common Mistakes 段
• 每个 MCP tool description 必须有 GOTCHA 段（和相似工具的区别）
• 持续迭代：猫踩了新坑就补进去，不是写完就不管

T0-3：不惊吓原则（知识工程指南）

Skill 的行为不得超出 description 承诺的范围。副作用动作（发消息、写数据、提交代码）必须在 description 里显式声明。

T0-4：反例至少出现两次（知识工程指南）

只写 "Use when" 不写 "Not for" = 边界模糊 → 误触发。反例要在 description 和 正文 都出现。 每个 skill 至少：2 条正例 + 2 条反例 + 1 条灰例。

T0-5：Skill 是文件夹，不只是 markdown（Anthropic）

用文件系统做 progressive disclosure：模板放 assets/、脚本放 scripts/、参考放 refs/。 Claude 会按需读取这些文件。重材料移到子文件，SKILL.md 正文控制在 150 行内。

T0-6：MCP Description 五要素（MCP 规范）

1. 做什么（一句话能力）
2. 什么时候用（触发关键词 / 用户常见表述）
3. 不做什么（排除错误路由 + 和相似 tool 的区别）
4. 产物（调用后会发生什么，含副作用）
5. GOTCHA（陷阱 + 易混工具区分）

缺一个就是不合格。详见 refs/mcp-tool-description-standard.md

Skill 类型（Anthropic 9 分类 + 我们的 3 分类）

SKILL.md 结构模板

---
name: skill-name-with-hyphens
description: >
  Use when [触发条件]. Not for [排除条件]. Output: [产出契约].
---
# Skill Name
## 价值门禁 / Why This Is a Skill（不是通用教程的理由）
## 核心知识 / Overview（1-2 句）
## 流程 / When to Use（触发 + 排除）
## Quick Reference（表格/bullet，供扫视）
## Common Mistakes（错误 → 后果 → 修复，持续迭代！）
## 验证 / Pressure Test（如何证明 skill 防住了真实失败）
## 和其他 skill 的区别（防误触发）
## 下一步（进入哪个 skill）

概念边界指南：易混概念必须在 description 里区分

写新 skill/MCP 时，问自己："有没有和现有工具/概念容易混的？"有就必须在 GOTCHA 里写清楚。

发布检查清单

1. 源文件：cat-cafe-skills/{skill-name}/SKILL.md（+ 支持文件）
2. 同步：pnpm sync:skills（不要手动 ln -s）
3. 注册：manifest.yaml 添加条目（triggers / not_for / output / next）
4. 验证：pnpm check:skills 全绿；若改动提到 API route / localhost / script / CLI command / 第一方执行面，commit 前还必须跑 pnpm check（会跑 skill surface guard）
5. Commit：包含 cat-cafe-skills/{skill-name}/

Common Mistakes

深入学习（按需阅读）

和其他 Skill 的区别

• tdd：写代码的测试驱动纪律 — writing-skills 是写 skill/MCP 的质量纪律
• quality-gate：代码完成后的自检 — writing-skills 是 skill 文件的质量检查
• self-evolution：从经验中提炼知识对象 — writing-skills 是把知识对象写成合格的 skill

下一步

完成 skill 后 → pnpm check:skills 全绿 → pnpm sync:skills → 如有新功能立项则 feat-lifecycle