# claude-api开盖：预装件的两张脸 ## 概述 Skills 生态的榜单看多了，容易漏掉一个事实：装机量最大的技能，从来不在任何热度榜上。它们随 Claude Code 本体出厂，和宿主一起分发——本期拆的 `claude-api` 就是其中之一。本次拆解的实证材料非常特殊：能 100% 确证的，是它暴露给模型的「门面」——description 原文，全部引自本机实装清单，一字未改；正文部分则按其自我声明与官方公开文档对齐，推断处均已标注。拆完你会发现：一件技能最值钱的一百个词，恰恰是读者永远看不到、模型每次都在读的那段。 ## 评测对比表 | 维度 | 权重 | 评分 | 依据 | |------|------|------|------| | 功能完整度 | 25% | ★★★★☆ | 触发清单点名六大主题（缓存/思考/工具/批量/引用/记忆），API 开发主链路全覆盖；深度调优仍需回官方文档 | | 设计质量 | 25% | ★★★★★ | TRIGGER/SKIP 双清单 + 代码特征触发 + 版本有效期，门面工程的教科书样本 | | 实战效果 | 20% | ★★★★☆ | 锚在 import 语句上触发，信号客观、误触发少；从其 SKIP 清单可反推作者对「抢活」问题有明确防御 | | 上手难度 | 15% | ★★★★★ | 预装，零配置，会话里提到 Claude API 即生效 | | 社区活跃度 | 15% | 随宿主分发 | 不走市场渠道，无 Star/下载量口径可查——这正是预装件的共性 | ## 一、生态的暗物质：榜单照不进的那半边 打开 skillsmp.com，目录里躺着 2300 多个技能；skills.sh 上新星周周换血；mcpservers.org 的 Agent Skills Library 收官方与社区精选。这是生态「看得见的半边」。 看不见的半边是预装件。以本机为例：清点出的四百余件技能里，有一批和 `example-skills:docx`、`obsidian:json-canvas` 这类带命名空间前缀的「外挂件」不同——`claude-api`、`code-review`、`verify`、`update-config`、`run` 这些没有任何前缀，与宿主能力（如会话配置、diff 审查）并列在一起。无前缀，就是自带件的记号：它们由官方随 Claude Code 一起写进安装包，不开箱选装、不进市场、不参与排名。 算一笔账就能理解这类件的分量：市场件的分发靠用户主动安装，一件技能星星再高，装机体量也就几千几万；预装件的分发曲线和宿主重合——宿主装到哪，它就在哪。论覆盖面，榜单上任何一个爆款在它面前都是少数派。 但预装件也付出了代价：它永远上不了榜。没有 Star 可刷，没有「本周新星」可上，社区讨论都绕着它走。这期专门开一次盖，把这个生态里的暗物质拖到灯下。 ## 二、两张脸：一件技能的显与隐 先补一点官方机制（出自 Anthropic 对 Agent Skills 的公开说明与官方仓库 anthropics/skills 的规范）：一件技能有两张脸。 **第一张脸是 description（外加名称），常驻上下文。**会话一开始，全部技能的门面就注入了模型——不管你这轮要不要用它。它的职责只有一个：让模型在合适的时机「想起」这件技能，在不合适的时机保持沉默。 **第二张脸是 SKILL.md 正文，按需加载。**只有门面命中、模型决定调用时，正文才被读入；正文里引用的参考文件和脚本，又是更深的第三层，用到才取。官方管这叫渐进披露（progressive disclosure）。 这个架构直接推出一个结论：**门面是稀缺资源。**粗算一下：四百多件技能、每件门面若占百余 token，常驻开销就是几万 token 的量级——相当于每次会话开场先读几万字中文。所以每件技能分到的门面预算极小，通常就一两句话。谁能在这一两句里把「什么时候用我、什么时候别用我」说清楚，谁就是门面工程的赢家。 `claude-api` 的门面，恰好是这一批自带件里写得最满、信息密度最高的一份。下面逐行拆。 ## 三、门面逐行拆：一段 description 的六处机关 先看原文（引自本机实装清单，节选关键句）： > claude-api: Build, debug, and optimize Claude API / Anthropic SDK apps. …… TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; …… SKIP: file imports `openai`/other-provider SDK …… ### 机关一：开头动词三元组 第一句 "Build, debug, and optimize Claude API / Anthropic SDK apps"——build、debug、optimize 三个动词，把用户的三种意图一次性收编：从零写、修出错的、调性能的，全都算它的活。多数社区件的门面只写「做什么」，不写「谁会来找我」；这一句是从用户动词的角度写的，一句顶三句。 ### 机关二：触发锚在代码特征上 TRIGGER 清单的第一条：`code imports 'anthropic'/'@anthropic-ai/sdk'`。这是全段最值钱的设计——**触发条件不锚在用户的说法上，锚在代码的客观特征上。**import 语句是二进制的：有就是有，没有就是没有，不存在同义词、翻译、口音问题。模型扫到项目里有 `import anthropic`，触发判断就不需要猜意图。 对比一下：如果你把触发写成「用户想调用大模型时」，那「帮我接个 AI」「加个对话功能」算不算？每个说法都是一道歧义题。锚在 import 上，一道都没有。 ### 机关三：同义词枚举，把叫法收拢 第二条："user asks for the Claude API, Anthropic SDK, or Managed Agents"。同一个东西，用户可能叫它 Claude API，可能叫 Anthropic SDK，也可能说 Managed Agents——门面把三种叫法并列枚举，一个都不漏。这是触发设计的笨办法，也是最可靠的办法：你永远不知道用户这一句会用哪个词，那就把词表列全。 ### 机关四：功能名词清单，门面即目录 第三条触发更进一步：用户要给应用**加功能**时也触发——加缓存、开思考模式、接工具调用、上批量处理、做引用标注等。注意这个名词单表的写法：caching、thinking、tool use、batch、citations……这不是随手举例，这份名单和 Anthropic 官方 API 文档的一级章节一一对应（该文档为公开资料，可自行核对）。 也就是说，**这段 description 本身就是正文的目录页。**用户问「怎么加 prompt caching」，门面命中；翻开正文，第一站就是缓存章节。门面写得像目录，用户的一切问法都能在门面上找到索引——这是「描述与正文同构」的范本。 ### 机关五：SKIP，负向空间 这是全段最罕见的设计。大多数社区件只写「什么时候用我」，从来不写「什么时候别用我」。`claude-api` 的门面里明确有一条 SKIP：文件 import 的是 `openai` 或其他供应商的 SDK，就跳过；文件名带 `*-generic.py` 这类通用实现、供应商无关的封装层，也让路。 为什么值钱？设想一个真实场景：项目里有一层多供应商抽象，同一个文件里 OpenAI 和 Anthropic 的调用都在。没有 SKIP，这件技能可能被整段代码误触发，把通用封装当成 Claude 专属逻辑来改，越帮越忙。有了 SKIP，就等于和相邻技能签了让位协议：**通用层归通用件，专用层归我。** 触发写得越多，误触发越多——这是门面工程的守恒律。正向清单负责「该来的来」，SKIP 负责「不该来的别来」，两头都写，才算把一个字段用到了底。 ### 机关六：版本梯子，门面里写着保质期 门面末尾还有一处容易被忽略的细节：它声明自己负责把存量应用迁移到新模型版本，并直接写出了版本阶梯——「4.5 → 4.6, 4.7, retired-model replacements」。 这是一件技能的保质期声明。模型半年一换代，写死的版本号、退役型号的迁移指南，全都会过期。把版本梯子直接写进门面，等于公开承认：**这件技能不是写完就完的资产，是需要随版本发布持续维护的活文档。**官方自己带头示范了这件事——对正在写技能的人来说，这是比任何写作技巧都重要的一课：门面里凡是会出现「当前最新」字样的地方，都要预留过期的那一天。 ## 四、正文对齐：目录能反查出多少东西 本次拆解能逐字实证的只有门面；正文部分按其自我声明反推，与官方公开文档的主题对齐，特此标注边界。 但能反推出的已经不少。门面点名的六大名词——prompt caching、extended thinking、tool use、batch、citations、memory——在官方文档里全是一级主题，各自有独立的章节和 API 参数族。可以合理推断正文以这六块为骨架铺开，每块给出 SDK 用法与最佳实践；而门面里被点名两次的 prompt caching（触发条件里有它，正文重点还有它）暴露了官方的优先级判断：**缓存是 Claude API 开发的头号省钱痛点，值得在门面上就替用户喊出来。** 这也解释了为什么这件技能的正文值得被触发一次：模型版本、缓存断点、计费细节这类知识迭代快、容易记错，交给一件由官方随版本维护的技能，比自己凭记忆写可靠得多。 ## 五、适用与不适用 **适用：** - 项目代码里已出现 `anthropic` / `@anthropic-ai/sdk` 导入，任何新增、修改、调优请求； - 用户明确提到 Claude API、Anthropic SDK、Managed Agents 任一叫法； - 想给现有应用加缓存、思考、工具、批量、引用、记忆中的任何一项； - 存量代码要从旧版本模型迁移到新版本。 **不适用（它的 SKIP 写得很明白）：** - 文件 import 的是 OpenAI 或其他供应商 SDK——那是别件的领地； - 供应商无关的通用封装层（`*-generic.py` 之类）——让位协议生效的地方； - 不写代码、只想对话的用户——这件是开发件，不是聊天件。 一句话总结人设：**只要你碰 Anthropic 的代码，我在；你写通用层，我让路。** ## 六、给技能作者的四件可抄之物 从这一件里能直接抄走的，是四个具体动作，不是四条泛泛原则： 1. **把触发锚在代码特征上。**import 语句、文件名、目录结构，都是零歧义信号。先找你领域里的「import anthropic」，再写触发句。 2. **配一条 SKIP 做让位协议。**写下你最容易误触发的那类文件，明确让给谁。负向清单是门面里最稀缺的诚意。 3. **在门面里写保质期。**凡是依赖「当前最新版本」的表述，标出版本梯子和迁移责任，提醒未来的自己来更新。 4. **让门面当正文的目录页。**功能名词清单与正文章节一一对应，用户的任何问法都能在门面上完成索引。 ## 本件工作流：两张脸如何接力 ```mermaid flowchart TD A["用户消息进入会话"] --> B{"门面匹配判断"} B -->|"无任何命中"| C["技能保持沉默"] B -->|"发现 anthropic 导入"| D["claude-api 门面命中"] B -->|"只谈 openai 导入"| E["SKIP 生效让路"] D --> F["载入 SKILL.md 正文"] F --> G{"需要更深的资料吗"} G -->|"要"| H["按需读取参考章节"] G -->|"不必"| I["按正文最佳实践作答"] H --> I I --> J["产出带缓存设计的代码"] ``` ## 安装 / 使用命令 - **claude-api：无需安装。**随 Claude Code 出厂预装，与宿主一同分发。验证方式：在项目里放一个 `import anthropic` 的文件，或在会话里直接说「帮我给这段代码加 prompt caching」。 - **想找社区同类件**（生态工具 CLI）：`npx skills find anthropic` - **手动安装社区技能的通用路径**：把含 SKILL.md 的技能目录复制进 `~/.claude/skills/<技能名>/`（官方约定的用户级目录）。 ## 门面写法对照：同批预装件的五种方言 同批预装的几件，门面各有写法，全部引自本机实装清单原文： | 技能 | 门面句式 | 特色机关 | |------|----------|----------| | claude-api | TRIGGER/SKIP 双清单 | 代码特征触发 + 版本梯子，唯一带负向清单的样本 | | update-config | 场景枚举触发 | 「from now on when X」「every time X」这类自动化口语直接入触发，附「allow npm …」「set DEBUG=…」式示例 | | verify | 动词定义 + 场景列表 | 强调「跑起来观察行为」而非看代码下结论，触发词全是验证场景 | | deep-research | 流程自述 + 前置反问 | 门面里写明 fan-out 检索、adversarially verify，并要求调用前先反问澄清问题 | | code-review | 分档参数式 | 同一件按 low/medium/high 输出不同数量与置信度的发现，强度档位写进门面 | ## 推荐排行榜：预装件门面工程 TOP5 1. **claude-api** —— 唯一同时写满正向触发与 SKIP 让位的样本，信息密度天花板； 2. **update-config** —— 把用户的自动化口语（「以后每次…」）直接做成触发词，想象力最佳； 3. **deep-research** —— 把「先反问再干活」写进门面，开工前先对齐需求，流程意识最强； 4. **verify** —— 用门面强制「运行验证」纪律，治「看代码下结论」的通病； 5. **code-review** —— 一件三档，按需输出，用最少的字数表达最多的行为差异。 ## 结语 榜单是生态的橱窗，预装件是生态的地基。`claude-api` 这次开盖证明了一件事：技能设计的天花板不在正文写了多少，而在那一两句常驻门面里——什么时候站出来，什么时候让路，什么时候承认自己会过期。下次写自己的第一件技能，先别急着堆正文，把那一百个词当一百块金子花。 ## 参考来源 1. 本机 Claude Code 实装技能清单（claude-api、update-config、verify、deep-research、code-review 等技能的 description 原文）— 本文全部引文与逐行拆解的实证来源 2. [anthropics/skills](https://github.com/anthropics/skills) — Anthropic 官方技能仓库，SKILL.md 规范与渐进披露机制的权威出处 3. [SkillsMP](https://skillsmp.com) — 2300+ 技能的可搜索目录，本文市场生态规模数据出处 4. [skills.sh](https://skills.sh) — 社区技能热度榜，本文「榜单生态」参照系 5. [MCPServers Agent Skills Library](https://mcpservers.org/agent-skills) — 官方与社区精选技能索引 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。