API 文档接 Agent 前先验

Agent-ready 文档不只是多放一个 llms.txt。现在产品可以同时暴露 capability summary、well-known skill index 和 MCP resources，让 Claude、Cursor、ChatGPT 或自定义客户端知道产品能做什么、该读哪段文档、哪些动作不能乱碰。

先选一个 Agent 任务

不要先写泛泛的产品介绍。先选一个窄任务：创建 webhook、排查 auth error、迁移废弃 endpoint、生成 support-safe 复现。Skill 里要写清输入、约束、预期输出，以及 agent 什么时候必须停下来。

先验发现路径

在 canonical docs domain 上确认 `/skill.md`、`/.well-known/agent-skills/index.json` 和 `/.well-known/skills/index.json` 能被访问。如果前面有 reverse proxy，这些路径要显式转发，否则用户和 agent 都会把它当成手动下载文件。

把说明和权限分开

Skill 负责教 agent 怎么做；MCP server、API token、OAuth app 或产品账号才决定它能不能读、写、删、提交反馈。文档 skill 不能被写成权限模型，也不能暗示安装 skill 就获得生产写权限。

• 安全说明：解释工作流、输入和约束。
• 动作权限：认证 MCP server、API key、OAuth scope 或产品角色。
• 上线证据：endpoint fetch、digest/version 证据、一段成功 workflow transcript。

跨客户端复用再用 MCP Resources

如果团队要在 Claude Code、Cursor、VS Code Copilot 或自定义 client 之间共用 skills，可以把 skill directory 暴露成 MCP resources。上线前至少证明 client 能 list skills、读取 `SKILL.md`、查看 supporting files。

一定测一个失败场景

让 agent 请求一个不支持或需要写权限的动作。好的 docs skill 应该让它改走安全路径、升级给人、或停止，而不是凭空假设自己有权限。