Docs as agent skills: what to publish before MCP rollout

Agent-ready documentation is not just an llms.txt file. A product can expose a capability summary, well-known skill indexes, and MCP resources so agents can discover what the product can do and how to use the docs safely.

Start With One Agent Task

Choose a narrow workflow before writing the skill: create a webhook, debug an auth error, migrate an endpoint, or generate a support-safe reproduction. The skill should name inputs, constraints, expected output, and when the agent should stop.

Publish Discovery Paths

Verify `/skill.md`, `/.well-known/agent-skills/index.json`, and `/.well-known/skills/index.json` on the canonical docs domain. If a reverse proxy sits in front of the docs, route those paths explicitly.

Separate Instructions From Authority

A skill teaches the workflow. The MCP server, API token, OAuth app, or product account decides what the agent can actually do. Do not let a docs skill blur read-only guidance with write-capable authority.

• Safe docs instruction: explain the workflow and required inputs.
• Action authority: authenticated MCP server, API key, OAuth scope, or product role.
• Launch proof: endpoint fetch, digest or version evidence, and one successful workflow transcript.

Use MCP Resources For Shared Skills

When teams maintain skills across Claude Code, Cursor, VS Code Copilot, or custom clients, expose the skill directory as MCP resources. Prove that clients can list skills, read `SKILL.md`, and inspect supporting files before rollout.

Test One Failure Case

Ask the agent for an unsupported or write-capable action. A useful docs skill should redirect, escalate, or stop instead of inventing authority it does not have.