跳到主要内容

Skill 设计套路

本章讲什么: 把仓库 17 个 skill 横着看,抽出反复出现、可直接抄的设计模式。每个模式都先白话点出「妙在哪」,再钉到真实文件。这是你写自己 skill 时最实用的一章。

0. 全家福(它们各管什么)​

四类(按用途归类;技能成员见 README.md 与 .claude-plugin/marketplace.json):

类别skill一句话
文档处理docx pdf pptx xlsx读/改/造 Office 与 PDF(source-available)
开发技术mcp-builder webapp-testing web-artifacts-builder claude-api skill-creator造 MCP、测网页、搭 artifact、写 Claude 应用、造 skill
创意设计algorithmic-art canvas-design frontend-design theme-factory slack-gif-creator生成艺术/版式/前端/主题/GIF
企业沟通brand-guidelines internal-comms doc-coauthoring品牌排版、内部沟通、文档协作

1. 模式 A:脚本当黑盒(省上下文)​

妙在哪。 大脚本若被读进上下文会吃掉宝贵窗口。所以把它们设计成只调用、不阅读的黑盒:先 --help 看用法,直接跑。

webapp-testing 把这条说得最直白:

「Always run scripts with --help first. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary. These scripts can be very large and thus pollute your context window.」

来源:skills/webapp-testing/SKILL.md:11-14、「Best Practices」(约 85 行)。它的 scripts/with_server.py 就是个黑盒——管理服务器生命周期,你只管 python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py(:39-50)。

这正是 01 章 L3「脚本可只执行、不读入」的落地。

2. 模式 B:用决策树替代一长串 if​

妙在哪。 「该走哪条路」用 ASCII 决策树画出来,比一段散文清楚得多,模型照着走不容易跑偏。

webapp-testing 开篇就是一棵树:

User task → Is it static HTML?
    ├─ Yes → 直接读 HTML 找 selector
    │         └─ 不行 → 当成动态(走下面)
    └─ No(动态) → 服务器起了吗?
        ├─ 否 → 跑 with_server.py --help,再写精简 Playwright 脚本
        └─ 是 → 侦察后行动:导航→等 networkidle→截图/查 DOM→用发现的 selector 执行

来源:skills/webapp-testing/SKILL.md:16-33(「Decision Tree」)。docx 也用「Quick Reference」小表做同样的事:读/造/改各走不同路(skills/docx/SKILL.md:14-19)。

3. 模式 C:reference 按域拆 + 正文只放总纲​

妙在哪。 跨多语言/多框架的 skill,若把所有方言塞进正文会爆 500 行;按域拆成 reference,正文只放工作流和『读哪份』的指针,模型只读相关那份。

mcp-builder 是范本:正文是 Phase 1-4 的工作流骨架,Python/TypeScript 的真正写法分别在 reference/python_mcp_server.md、reference/node_mcp_server.md,正文用一行链接挂出来:

For TypeScript: [⚡ TypeScript Guide](./reference/node_mcp_server.md)
For Python:     [🐍 Python Guide](./reference/python_mcp_server.md)

来源:skills/mcp-builder/SKILL.md:60-66。它的 reference/ 目录里 4 份文档(evaluation.md/mcp_best_practices.md/node_mcp_server.md/python_mcp_server.md)分别在不同 Phase 才被读入。claude-api 更进一步,按语言开了 python/ typescript/ go/ java/ php/ ruby/ csharp/ curl/ shared/ 子目录。

4. 模式 D:推式触发描述(claude-api 是极致)​

妙在哪。 description 是触发器(index §3)。claude-api 把它写成了一套带 TRIGGER/SKIP 双向规则的小决策器,专治漏触发:

  • TRIGGER:prompt 里出现 Claude/Anthropic 任意形态(claude-*、@anthropic-ai…)、问到 LLM(定价/选型/限流)、或任务是「LLM 形状」但没说提供商时——都要在打开目标文件前先读本 skill。
  • SKIP(压过所有 TRIGGER):已在做别的提供商(OpenAI/GPT/Gemini…),或 grep 到 openai|langchain_openai|… 命中时——先跑这个 grep,别凭空读文件。

来源:skills/claude-api/SKILL.md 的 frontmatter description(多行块,约 3-7 行)。

这把 skill-creator 那条「description 要 pushy、所有『何时用』都进 description」(skills/skill-creator/SKILL.md:67)用到了极限——连「什么时候别用」都写进去了,这是减少误触发的高级招。

5. 模式 E:把易漂移的知识做成对照表​

妙在哪。 模型训练有截止日,某些 API 形状会变;与其让它凭记忆,不如在 skill 里摆一张「旧记忆 vs 现行」对照表,显式纠偏。

claude-api 有一张「API Drift」表,例如:

领域旧记忆(可能已过期)现行 API
extended thinkingthinking: {type:"enabled", budget_tokens:N}4.6+ 用 thinking: {type:"adaptive"};新模型上 budget_tokens 被 400 拒

来源:skills/claude-api/SKILL.md「⚠️ API Drift」表(约「Extended thinking」行)。配套还有一句明确的优先级:skill 里的 {lang}/ 文件权威于你回忆的模式(同节)。这是「用 skill 给模型打补丁」的典型用法——把会变的事实从模型权重里『外置』到可更新的 skill 文件里。

6. 模式 F:共享库 + ZIP-of-XML 编辑哲学(office 四件套)​

妙在哪。 docx/pptx/xlsx 都要操作「本质是 ZIP 包着 XML」的 Office 文件,于是它们共享同一套 office/ 工具库(unpack.py 解包美化 XML、pack.py 校验回包、validate.py、soffice.py 调 LibreOffice、helpers/、validators/)。

经核对,docx 与 xlsx、docx 与 pptx 的 scripts/office/ 目录逐文件无差异(diff -rq 无输出)——是同一份库被各 skill 复用。

编辑哲学(以 docx 为例)是固定三步:

unpack.py document.docx unpacked/    # 1 解包:抽 XML、美化、合并相邻 run、智能引号转实体
  → 用 Edit 工具直接改 word/*.xml     # 2 编辑:别写 Python 脚本,Edit 看得见改了啥
pack.py unpacked/ out.docx --original document.docx  # 3 回包:校验 + 自动修复 + 压缩

来源:skills/docx/SKILL.md「Editing Existing Documents」(约 398-440 行);unpack.py 的职责见其文件头注释(skills/docx/scripts/office/unpack.py:1-17)。

值得带走的两个细节:

  • 智能引号转 XML 实体:unpack.py 把 “”‘’ 转成 “ 等实体,让它们在编辑中存活(unpack.py 的 SMART_QUOTE_REPLACEMENTS)。docx 正文还给了一张实体对照表(skills/docx/SKILL.md:421-427)。
  • 自动修复有边界:pack.py 能修「durableId 过大」「<w:t> 缺 xml:space="preserve"」,但不修畸形 XML、错误嵌套、缺关系、schema 违规(skills/docx/SKILL.md:442-447)——诚实地划清了工具能力的边界。

7. 模式 G:把「全是坑」的领域写成 CRITICAL 清单​

妙在哪。 有些库默认值反直觉(docx-js 默认 A4 不是 Letter),错一个就渲染崩。docx 用一节「Critical Rules for docx-js」把这些坑一次列清,每条都点出后果而非空喊规则:

  • 「Tables need dual widths」——columnWidths 和每个 cell 的 width 都要设且要相等,否则某些平台渲染错位(skills/docx/SKILL.md:178、「Critical Rules」约 386-389 行)。
  • 「Use ShadingType.CLEAR(not SOLID)」——否则表格出现黑底(:195, 390)。
  • 「Never use unicode bullets」——要用 LevelFormat.BULLET 的 numbering 配置(:142-174, 383)。

这与 skill-creator「解释 why、少用全大写 MUST」的建议略有张力——但这里每条 CRITICAL 都带了后果解释,属于「值得喊」的那种。

8. 边界与局限(诚实)​

  • 本章对 mcp-builder、claude-api 的 reference/、{lang}/ 子目录只读到 SKILL.md 层的指针与目录布局,未逐份核读其内部全文;引用均限于 SKILL.md 明示与目录事实。
  • office/ 的「逐文件无差异」基于 diff -rq 的目录比对结论;未逐行比对每个文件内容。
  • 创意类 skill(algorithmic-art/canvas-design/theme-factory 等)未逐一展开,模式 A-G 已覆盖其共性套路。

9. 代码地图​

模式文件路径符号 / 锚点
A 脚本黑盒skills/webapp-testing/SKILL.md「Helper Scripts」「Best Practices」
A 黑盒脚本本体skills/webapp-testing/scripts/with_server.py—(--help)
B 决策树skills/webapp-testing/SKILL.md「Decision Tree」
C reference 分域skills/mcp-builder/SKILL.md「Documentation Library」
C 多语言子目录skills/claude-api/python/,typescript/,shared/
D 推式触发 + SKIPskills/claude-api/SKILL.mdfrontmatter description
E API 漂移表skills/claude-api/SKILL.md「⚠️ API Drift」表
F 共享 office 库skills/docx/scripts/office/unpack.py,pack.py,SMART_QUOTE_REPLACEMENTS
F 编辑三步 + 自动修复边界skills/docx/SKILL.md「Editing Existing Documents」
G CRITICAL 清单skills/docx/SKILL.md「Critical Rules for docx-js」