系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第十五篇。第十三篇我们拆了文档处理类 Skill第十四篇拆了开发工具类 Skill。这一篇继续看第三类典型形态知识库型 Skill。它的核心不是直接操作文件也不是启动工具验证环境而是把权威资料、版本差异、语言示例和决策规则组织起来帮助 Agent 在变化很快的技术领域里少凭记忆、多查依据。1. 什么是知识库型 Skill知识库型 Skill 的核心目标是把权威资料变成 Agent 可检索、可执行、可更新的行动指南。它不是普通文档目录。普通文档目录更像给人看的资料库。知识库型 Skill 要服务的是 Agent 的工作流程。它需要回答这些问题用户什么时候需要这套知识哪些信息必须先查不能凭记忆回答不同语言、平台、版本应该读哪份资料哪些内容可能过期需要查 live source如果资料缺失或网络不可用应该怎么降级哪些历史写法已经过时不能继续使用最终输出代码、配置或建议时如何标注依据和限制所以知识库型 Skill 不是“把资料放进references/”这么简单。它真正要设计的是Agent 如何在资料之间做路由。2. 为什么claude-api是典型案例claude-api是一个非常典型的知识库型 Skill。它处理的是 Claude API 和 Anthropic SDK 相关任务。这类任务有几个特点。第一变化快。模型 ID、参数、beta header、SDK 方法名、平台能力、迁移规则都会变化。第二语言多。同一个功能在 Python、TypeScript、Java、Go、Ruby、C#、PHP、cURL 中写法不同。第三平台多。同样是 Claude可能运行在First-party Claude API。Claude Platform on AWS。Amazon Bedrock。Google Vertex AI。Microsoft Foundry。第四错误成本高。如果 Agent 凭记忆写错 SDK 方法名、过时参数或不支持的平台功能用户拿到的代码可能直接不能运行。第五任务边界容易混淆。用户可能问的是 Claude也可能问的是 OpenAI、Gemini、Llama、Mistral、Ollama或者一个没有明确供应商的“LLM 应用”。这类场景特别适合知识库型 Skill。3. 知识库型 Skill 和前两类有什么不同可以先用一张表对比。类型核心对象关键能力典型风险文档处理类文件格式解包、提取、转换、校验文件损坏、格式丢失开发工具类本地环境和工具链启动、测试、观察、反馈命令副作用、测试不稳定知识库型权威资料和版本规则检索、路由、对比、更新凭记忆写错、资料过期知识库型 Skill 的核心不在于“执行工具”而在于“使用正确知识”。当然它也可能包含脚本。但最重要的通常是description触发策略。SKILL.md中的决策树。references/或分语言目录。live source 路由。过时写法和当前写法对照。4.claude-api的 description 为什么这么重要claude-api的 description 很长。这不是偶然。因为它需要处理复杂召回。它不仅要在用户明确提到 Claude 或 Anthropic 时触发还要在很多 LLM 相关任务中提醒 Agent不要凭记忆回答先查这套资料。它的触发信号包括用户提到 Claude、Anthropic、Fable、Opus、Sonnet、Haiku。用户提到anthropic、anthropic-ai、claude-*等标识。用户询问模型、价格、限制、缓存、token。用户要做 agent、MCP、tool definition、multi-agent、RAG、LLM judge、computer use。用户要生成、总结、抽取、分类、改写或对话类 LLM 应用。用户要调试 refusal、cutoff、streaming、tool calls、tokens 等问题。这说明知识库型 Skill 的 description 经常需要更“积极”。原因是技术知识会过期。如果 Agent 没有触发知识库 Skill就很容易用训练记忆写出旧 API。5.claude-api的 skip 条件同样关键claude-api不只是积极触发。它也有明确 skip 条件。例如当项目或用户明确使用其他供应商时OpenAI / GPT。Gemini。Llama。Mistral。Cohere。Ollama。这时不应该把 Claude SDK 写进别人的项目。它甚至要求在没有明确供应商时先 grep 项目中是否存在其他 provider 标记。这体现了一个知识库型 Skill 的重要边界不能因为自己资料完整就强行接管相邻技术栈。知识库型 Skill 往往覆盖很大的知识面。越是这样越需要清楚排除条件。6.claude-api的第一条原则不要凭记忆猜 SDK 用法这个 Skill 最值得学习的一条规则是Never guess SDK usage.它明确要求函数名必须来自文档。类名必须来自文档。命名空间必须来自文档。方法签名必须来自文档。import path 必须来自文档。不能从一种语言的 SDK 形状推断另一种语言。这对 API 类知识库非常关键。因为模型很容易“看起来合理地猜”。比如 Python、TypeScript、Go、Java SDK 的调用方式可能差异很大。如果 Agent 看到 cURL 示例就推断出 Go SDK 类型名风险很高。所以知识库型 Skill 应该把“不猜”写成硬约束。7. API 漂移是知识库型 Skill 的核心问题API 漂移指的是你记得的旧写法和当前真实 API 已经不一致。claude-api在主文件里专门列了 API Drift 表。它把常见旧写法和当前写法放在一起。例如extended thinking 参数变化。web search / web fetch 工具类型变化。PHP 参数命名变化。structured outputs 参数变化。模型 ID 不应该自行拼接日期后缀。这种设计非常适合知识库型 Skill。因为 Agent 不只是需要“知道当前写法”还需要知道哪些旧写法最容易被误用。这能对抗模型训练记忆。8. 为什么要列出过时写法很多人设计知识库时只写当前正确做法。但对 Agent 来说这还不够。因为 Agent 可能从训练数据里“记得”旧做法。如果 Skill 只说当前应该使用 adaptive thinking。可能不如这样有效不要使用 thinking: {type: enabled, budget_tokens: N} 作为新模型的默认写法当前 Claude 4.6 推荐使用 thinking: {type: adaptive}部分新模型会拒绝旧参数。后者同时做了三件事指出旧写法。指出当前写法。指出旧写法的风险。知识库型 Skill 应该主动收集这类漂移点。9.claude-api的主文件承担什么职责claude-api/SKILL.md很长但它不是无意义堆资料。它承担几类入口职责。部分作用description决定什么时候触发以及什么时候跳过Before You Start检查是否是 Anthropic 项目避免误改其他 providerOutput Requirement约束必须使用官方 SDK 或明确 raw HTTPDefaults给出默认模型、thinking、streaming 等策略API Drift告诉 Agent 哪些记忆可能过期Language Detection决定读取哪个语言目录Subcommands支持特定流程比如迁移Decision Tree帮 Agent 选择 Claude API、tool use、Managed Agents 等表面这说明主文件不是“所有知识的合集”。它更像路由器。它告诉 Agent先判断什么。再读哪份资料。哪些规则不能违反。哪些情况必须停下来确认。10. 语言目录按实现环境拆分知识claude-api的目录中有多个语言分支python/claude-api/ typescript/claude-api/ java/claude-api/ go/claude-api/ ruby/claude-api/ csharp/claude-api/ php/claude-api/ curl/每个语言目录下通常有README.md。streaming.md。tool-use.md。files-api.md。batches.md。managed-agents/README.md。这就是按语言拆分。为什么要这样拆因为不同语言的 SDK 不是同一种语法。把所有语言都塞进一个SKILL.md会导致上下文过大。Agent 可能混用语言。示例之间互相干扰。维护成本很高。按语言拆分后Agent 可以先判断项目语言再只读相关目录。11. shared 目录跨语言共享知识除了语言目录claude-api还有shared/。这里放的是跨语言共享知识。例如shared/models.md shared/model-migration.md shared/platform-availability.md shared/prompt-caching.md shared/token-counting.md shared/tool-use-concepts.md shared/live-sources.md shared/anthropic-cli.md这些内容不属于某一种语言。比如模型能力。平台可用性。迁移规则。token counting。prompt caching。live documentation source。CLI 认证方式。这类信息放在shared/更合理。Agent 在任何语言项目中都可能需要读它们。12. live-sources给知识库留出更新通道知识库型 Skill 最怕过期。claude-api通过shared/live-sources.md解决这个问题。它列出在什么情况下应该 WebFetch 最新资料用户明确问“latest” 或 “current”。缓存内容看起来不正确。用户问到缓存中没有覆盖的新功能。用户需要具体 API 细节或示例。同时它列出官方文档和 SDK 仓库地址。这很重要。知识库型 Skill 不应该假设自己永远最新。更好的策略是Skill 内保存稳定高频知识。对易变信息保存 live source 路由。当用户需要最新信息时主动查权威来源。查询失败时说明可能过期并使用缓存内容谨慎回答。13. 平台可用性避免把一个平台的能力误用到另一个平台Claude API 相关任务还有一个常见坑某个功能在 first-party API 可用但在 Bedrock、Vertex、Foundry 上不一定可用。shared/platform-availability.md解决这个问题。它用一张表标记不同平台支持情况。平台包括1P Claude API。Claude Platform on AWS。Amazon Bedrock。Google Vertex AI。Microsoft Foundry。功能包括Messages。streaming。tool use。PDF input。structured outputs。prompt caching。token counting。server-side tools。Managed Agents。Files API。这就是知识库型 Skill 的典型价值。如果没有这张表Agent 可能会把某个平台不支持的功能写进代码。14. 模型迁移知识库不只是查询还能指导流程shared/model-migration.md是另一个重要例子。它不是简单列模型。它是一套迁移流程。比如/claude-api migrate子命令会要求先确认迁移范围。再分类每个文件。区分调用 API 的文件、定义模型的文件、字符串引用、后缀变体。再按目标模型读取具体 breaking changes。最后验证迁移。这说明知识库型 Skill 可以包含“操作流程”。它不只是百科。它可以把复杂升级经验变成步骤化工作流。15. 知识库型 Skill 的两种资料设计知识库型 Skill 时可以把资料分成两类。类型特点例子稳定知识不频繁变化适合缓存进仓库概念解释、目录结构、常见流程易变知识会随版本、平台、SDK 更新模型 ID、价格、参数、SDK 方法名、平台支持稳定知识可以直接写在 Skill 中。易变知识要有更新机制。比如标注缓存日期。提供 live source。明确何时需要 WebFetch。不确定时不要编造。让用户知道信息可能变化。16. 知识库型 Skill 的信息架构一个成熟知识库型 Skill 通常包含这些层。knowledge-skill/ ├── SKILL.md ├── shared/ │ ├── decision-tree.md │ ├── version-matrix.md │ ├── migration-guide.md │ └── live-sources.md ├── python/ │ └── README.md ├── typescript/ │ └── README.md ├── java/ │ └── README.md └── examples/ └── common-patterns.md不是每个知识库都需要这么复杂。但claude-api这种多语言、多平台、多版本场景就非常适合。17.SKILL.md应该像路由器知识库型 Skill 的SKILL.md不应该试图装下所有资料。它应该像路由器。也就是说它要告诉 Agent是否应该使用这个 Skill。任务是否属于当前技术栈。需要先读哪个共享文件。需要再读哪个语言文件。哪些信息必须查 live source。哪些旧写法必须避免。如果资料不足应该如何降级。一个好的SKILL.md会让 Agent 少读资料但读对资料。18. Reference Routing 怎么写知识库型 Skill 特别需要 Reference Routing。可以写成## Reference Routing - Read shared/platform-availability.md before writing code for Bedrock, Vertex, Foundry, or Claude Platform on AWS. - Read shared/model-migration.md when the user asks to migrate model IDs or update old Claude API code. - Read shared/live-sources.md when the user asks for latest/current model, pricing, or SDK behavior. - Read python/claude-api/README.md for Python SDK code. - Read typescript/claude-api/README.md for TypeScript or JavaScript SDK code. - Read curl/examples.md only when the user explicitly asks for cURL or raw HTTP.这比把所有文件都读一遍要好很多。它降低上下文成本也减少错误混用。19. 语言检测应该放在主流程前面claude-api明确要求先检测语言。比如*.py、requirements.txt、pyproject.toml表示 Python。*.ts、*.tsx、package.json、tsconfig.json表示 TypeScript。*.java、pom.xml、build.gradle表示 Java。*.go、go.mod表示 Go。*.rb、Gemfile表示 Ruby。*.cs、*.csproj表示 C#。*.php、composer.json表示 PHP。这个步骤很关键。如果不先检测语言Agent 可能会用 Python 示例写 TypeScript 项目或者把 cURL payload 直接翻译成不正确的 SDK 调用。知识库型 Skill 里语言检测是一种资料路由。20. Provider 检测同样重要claude-api还要求检查项目里是否已经使用其他 provider。例如openai。langchain_openai。google.generativeai。mistralai。cohere。ollama。如果发现这些标记就不能直接把 Anthropic SDK 写进去。应该停下来确认用户是否想把项目切到 Claude。还是想保留原 provider。是否需要 provider-neutral 实现。这体现了知识库型 Skill 的安全边界。知识库越专业越要避免过度套用。21. Defaults知识库也可以承载默认决策claude-api中有默认模型、thinking、streaming 等建议。这类默认值很有用但也有风险。它们需要满足两个条件有明确来源。可被用户显式覆盖。比如Unless the user requests otherwise...这类写法告诉 Agent默认怎么做。用户明确要求时以用户为准。知识库型 Skill 经常需要默认决策。例如内部 API 平台也可能需要默认使用 v2 API。默认使用生产只读 token。默认生成 TypeScript SDK 示例。默认使用分页接口而不是全量导出。但默认决策必须写清边界。22. Authentication知识库要覆盖真实环境问题claude-api不只讲 API 调用还讲认证。比如它说明ANTHROPIC_API_KEY未设置不代表没有凭证。SDK 和 CLI 可能读取 OAuth profile。raw HTTP 和 SDK 的认证方式不同。什么时候需要询问用户 API key。这说明知识库型 Skill 不能只放“理想代码示例”。它还要覆盖真实工程环境。很多 API 集成失败不是因为核心调用错了而是因为认证来源不清。环境变量冲突。平台凭证不同。用户使用 CLI profile。原始 HTTP header 写错。这些都应该进入知识库。23. 什么时候需要 live source不是所有问题都要联网查。如果每次都 WebFetch效率低用户体验也差。但这些场景应该查 live source用户问“最新模型是什么”。用户问“当前价格是多少”。用户问“某功能现在是否支持 Bedrock”。用户问缓存中没有的新功能。用户指出你给的答案可能过时。代码涉及具体 SDK 方法但本地资料没有覆盖。这就是知识库型 Skill 的平衡常用稳定知识本地化易变关键知识实时化。24. 如果 live source 失败怎么办知识库型 Skill 还要设计降级策略。live-sources.md给出的思路是使用缓存内容。说明数据可能过期。建议用户查官方文档或 SDK 仓库。这很务实。不能因为无法联网就一直重试。也不能装作已经查到了最新信息。正确态度是我会基于 Skill 中缓存的资料给出答案但这类信息可能随版本变化如果需要绝对最新结果需要再核对官方文档。这比凭空确定要可靠得多。25. 知识库型 Skill 的输出要求知识库型 Skill 不只影响读取资料也会影响最终输出。对于 API 类任务输出通常要包含正确代码。使用的 SDK 或 raw HTTP 方式。关键参数解释。平台限制。版本或模型约束。需要用户配置的环境变量。未验证或不确定信息。如果是迁移任务还要包含修改范围。迁移前后差异。移除的旧参数。新增的参数。验证命令。残余风险。知识库型 Skill 的输出不能只是“答案”还要让用户知道依据和边界。26. 反例一个糟糕的 API 知识库 Skill不推荐这样设计api-helper/ └── SKILL.mdSKILL.md里写Use this skill when the user asks about our API. To call the API, send a POST request with your token.问题很多不知道触发哪些任务。不知道 API 有哪些版本。不知道支持哪些语言。不知道认证方式。不知道哪些资料可能过期。没有错误码。没有迁移指南。没有平台差异。没有 live source。没有 skip 条件。这不是知识库型 Skill只是提示词片段。27. 正例一个更好的 API 知识库 Skill更好的结构是internal-api-guide/ ├── SKILL.md ├── shared/ │ ├── overview.md │ ├── auth.md │ ├── version-matrix.md │ ├── error-codes.md │ ├── pagination.md │ ├── migration-v1-to-v2.md │ └── live-sources.md ├── typescript/ │ ├── README.md │ └── examples.md ├── python/ │ ├── README.md │ └── examples.md └── examples/ ├── minimal-request.md └── webhook-handler.md这个结构清楚很多。SKILL.md负责路由。shared/存放跨语言知识。语言目录存放 SDK 示例。live-sources.md指向最新 OpenAPI、SDK 仓库或内部文档。28. 为内部 API 平台设计知识库型 Skill现在进入实践任务为一个内部 API 平台设计知识库型 Skill 的参考资料目录。假设这个内部平台叫Acme API Platform它支持REST API。TypeScript SDK。Python SDK。OAuth 认证。Webhook。v1 到 v2 迁移。多环境dev、staging、prod。我们要设计一个 Skill。29. 目录草图可以这样设计acme-api-platform/ ├── SKILL.md ├── shared/ │ ├── overview.md │ ├── authentication.md │ ├── environments.md │ ├── version-matrix.md │ ├── error-codes.md │ ├── pagination.md │ ├── webhooks.md │ ├── migration-v1-to-v2.md │ └── live-sources.md ├── typescript/ │ ├── README.md │ ├── client-setup.md │ └── examples.md ├── python/ │ ├── README.md │ ├── client-setup.md │ └── examples.md └── examples/ ├── minimal-read-request.md ├── create-resource.md └── webhook-handler.md这个结构借鉴了claude-api的思路。按语言拆 SDK 用法。按 shared 拆跨语言知识。按 live-sources 保留更新入口。30.description草案可以这样写name:acme-api-platformdescription:Reference for Acme API Platform integration,including REST endpoints,TypeScript and Python SDK usage,authentication,pagination,webhooks,error handling,version migration,and environment differences. Use this skill whenever the user asks to build,debug,migrate,or review code that calls Acme APIs or SDKs. Read the relevant language-specific files before writing code; do not guess SDK method names,auth headers,endpoint paths,or version-specific parameters from memory. Do not use this skill for unrelated third-party APIs unless the user explicitly wants to switch to Acme.这段 description 包含能力定义。输入对象。触发场景。强约束不要猜 SDK、header、endpoint、参数。排除条件。31.SKILL.md主流程草案可以这样写## Before You Start Check whether the target code already uses Acme API, another provider, or a provider-neutral abstraction. Do not replace another provider with Acme unless the user explicitly asks. ## Workflow 1. Identify the users task: new integration, debugging, migration, webhook, auth, pagination, or error handling. 2. Detect the project language from files and package metadata. 3. Read shared/version-matrix.md when the task mentions API versions. 4. Read shared/authentication.md before writing auth code. 5. Read the language-specific SDK file before writing SDK calls. 6. Read shared/live-sources.md when the user asks for current endpoint behavior or the cached docs do not cover the feature. 7. Write code or guidance using only documented methods and parameters. 8. Mention any platform, environment, or version assumptions.这个流程的重点是先分类再路由。32. Reference Routing 草案可以写## Reference Routing - Read shared/authentication.md for OAuth, API keys, token refresh, and credential precedence. - Read shared/environments.md before writing base URLs or environment-specific config. - Read shared/version-matrix.md before using version-specific endpoints. - Read shared/error-codes.md when debugging failed API calls. - Read shared/pagination.md before implementing list/search endpoints. - Read shared/webhooks.md before implementing webhook verification or retry handling. - Read shared/migration-v1-to-v2.md when the user asks to upgrade old code. - Read typescript/README.md for TypeScript SDK usage. - Read python/README.md for Python SDK usage. - Read shared/live-sources.md when the user asks for latest/current behavior.这能避免 Agent 盲读所有文件。33. shared 文件应该怎么写每个 shared 文件都应该有明确职责。33.1authentication.md包含支持的认证方式。token 获取方式。环境变量命名。token refresh。常见错误。不要把密钥写进代码。33.2version-matrix.md包含v1、v2、beta 的差异。endpoint 变化。参数变化。废弃字段。迁移建议。33.3error-codes.md包含HTTP 状态码。业务错误码。是否可重试。用户应如何修复。33.4pagination.md包含limit 默认值。最大 limit。cursor 或 offset。has_more。防止一次拉全量。33.5live-sources.md包含OpenAPI 文档地址。SDK 仓库地址。changelog 地址。内部发布说明地址。什么时候必须查最新资料。34. 语言目录应该怎么写语言目录不要只是复制 REST 文档。它应该写 SDK 真实用法。例如 TypeScript 目录包含# TypeScript SDK ## Client Setup - Package name: - Import path: - Client constructor: - Auth configuration: ## Common Operations - List resources: - Get resource: - Create resource: - Update resource: - Delete resource: ## Streaming or Pagination - Cursor handling: - Retry handling:Python 目录也类似但要写 Python 真实包名、导入路径和方法签名。不要从 TypeScript 推断 Python。也不要从 REST endpoint 推断 SDK 方法名。35. 过时写法对照表内部 API 平台也应该维护 API Drift 表。例如AreaStale priorCurrentBase URLhttps://api.acme.internal/v1https://api.acme.internal/v2Auth headerX-API-KeyAuthorization: Bearer tokenPaginationpage/page_sizecursor/limitUser ID fielduser_iduserIdWebhook signatureX-SignatureAcme-Signature这张表的作用不是给人怀旧。它是为了提醒 Agent你可能会记得旧写法但现在不能这么写。36. 知识库型 Skill 的测试 prompt知识库型 Skill 也要测试。可以设计 6 条“帮我用 TypeScript 接入 Acme API 的 list users。”“这个 Python SDK 调用报 401帮我排查。”“把 v1 的分页逻辑迁到 v2。”“实现 webhook 签名校验。”“当前 v2 create order 支持哪些字段” 这应该触发 live source 或说明缓存限制。“这个项目使用 OpenAI帮我接入 Acme。” 这应该先确认是否切换 provider。评估重点是否先检测语言。是否读取认证资料。是否避免猜 SDK 方法名。是否识别迁移任务。是否在 current/latest 问题上查 live source。是否避免误改其他 provider 项目。37. 知识库型 Skill 的常见错误37.1 错误一把所有资料塞进SKILL.md这会导致上下文过大。主文件应该负责路由长资料应该拆分。37.2 错误二没有版本边界API 类知识如果不写版本Agent 很容易把 v1、v2、beta 混在一起。37.3 错误三没有过时写法对照只写当前写法无法有效对抗模型旧记忆。37.4 错误四没有 live source如果 API 变化快知识库必须有更新入口。37.5 错误五跨语言猜测 SDK不要从 Python 代码推断 Java SDK。不要从 cURL 推断 Go 类型名。37.6 错误六没有排除条件如果用户在做其他 provider不要强行切到自己的 API。37.7 错误七把示例写得太理想化真实 API 集成还需要认证、错误处理、分页、重试、环境配置。知识库不应该只放 happy path。38. 知识库型 Skill 自查清单设计知识库型 Skill 时可以用这张表。检查项问题触发description 是否覆盖真实任务表达排除是否排除了相邻技术栈或其他 provider路由SKILL.md是否说明先读哪些资料版本是否有版本矩阵或迁移指南漂移是否列出常见过时写法和当前写法语言是否按语言拆分 SDK 用法平台是否说明不同平台能力差异live source是否说明何时查最新文档降级live source 不可用时是否有处理策略安全是否避免泄露密钥或误改其他 provider输出是否要求标注假设、版本和未验证信息测试是否有触发、路由、迁移和过期信息测试39. 小结这一篇拆解了知识库型 Skill并以claude-api为主要案例。可以记住三句话知识库型 Skill 的核心不是堆文档而是把权威资料组织成可路由、可更新、可执行的行动指南。对 API、SDK、模型、平台这类易变知识必须显式处理 API 漂移、版本差异、语言差异和 live source。SKILL.md应该像路由器负责触发、排除、语言检测、资料路由和强约束具体细节再按需加载。如果第十四篇关注的是“如何通过工具获得真实反馈”第十五篇关注的就是“如何通过权威资料避免错误记忆”。下一篇将回到团队落地Skill 作为团队资产应该如何版本管理、分发、审核、测试和治理。40. 实践任务请为一个内部 API 平台设计知识库型 Skill 的参考资料目录。要求包含SKILL.md。至少一个shared/目录。至少两个语言目录。版本矩阵。认证说明。错误码说明。live source 路由。API 漂移对照表。可以从这个目录开始acme-api-platform/ ├── SKILL.md ├── shared/ │ ├── overview.md │ ├── authentication.md │ ├── environments.md │ ├── version-matrix.md │ ├── error-codes.md │ ├── pagination.md │ ├── webhooks.md │ ├── migration-v1-to-v2.md │ └── live-sources.md ├── typescript/ │ ├── README.md │ ├── client-setup.md │ └── examples.md ├── python/ │ ├── README.md │ ├── client-setup.md │ └── examples.md └── examples/ ├── minimal-read-request.md ├── create-resource.md └── webhook-handler.md40.1 descriptionname:acme-api-platformdescription:Reference for Acme API Platform integration,including REST endpoints,TypeScript and Python SDK usage,authentication,pagination,webhooks,error handling,version migration,and environment differences. Use this skill whenever the user asks to build,debug,migrate,or review code that calls Acme APIs or SDKs. Read the relevant language-specific files before writing code; do not guess SDK method names,auth headers,endpoint paths,or version-specific parameters from memory. Do not use this skill for unrelated third-party APIs unless the user explicitly wants to switch to Acme.40.2 Reference Routing- Read shared/authentication.md before writing auth code. - Read shared/version-matrix.md before using version-specific endpoints. - Read shared/error-codes.md when debugging API failures. - Read shared/pagination.md before implementing list/search endpoints. - Read shared/migration-v1-to-v2.md for migration tasks. - Read typescript/README.md for TypeScript SDK code. - Read python/README.md for Python SDK code. - Read shared/live-sources.md when the user asks for latest/current behavior.40.3 API Drift 表| Area | Stale prior | Current | | --- | --- | --- | | Base URL | https://api.acme.internal/v1 | https://api.acme.internal/v2 | | Auth header | X-API-Key | Authorization: Bearer token | | Pagination | page / page_size | cursor / limit | | Webhook signature | X-Signature | Acme-Signature |完成这个练习后你会更清楚地看到知识库型 Skill 的关键不是“资料越多越好”而是让 Agent 在正确时机读正确资料并在资料可能过期时知道去哪里核对。