Agent Skill Discovery via Well-Known URI

1. Introduction

1.1 Goal

Many sites expose an API. Agents need a clear way to learn how to use it.

Today, that guidance is often buried in docs. It may be in a README, an OpenAPI file, a private page, or a code comment. Agents then guess too much.

This specification puts a small agent guide at a fixed URL:

/.well-known/skills.md

The guide should be plain Markdown. It should be easy to read. It should tell an agent what the API is for and how to act safely.

1.2 Terms

The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY use the meanings from BCP 14.

• Origin: The scheme, host, and port of a URL, such as https://api.example.com.
• Public API: Any internet-facing HTTP API or service that a client can call.
• Skills document: The Markdown file at /.well-known/skills.md.
• Discovery document: The optional JSON file at /.well-known/mcp.json.
• Client: Software that reads these files.
• Tool: A service or API action a client can call.
• MCP server: A service that implements the Model Context Protocol.

1.3 Basic Rule

If an origin exposes a public API, it SHOULD serve /.well-known/skills.md.

If an origin has no public API and no agent actions, it MAY return 404 Not Found.

If a site also wants JSON discovery, it MAY serve /.well-known/mcp.json.

1.4 Autoskill Generation

The skills document may be written by hand. It may also be generated.

This project recommends github.com/Leopere/autoskill-md for generating Markdown skills files. The generator should read source code, route files, OpenAPI files, or other API metadata. It should then write a clear skills.md file for agents.

The output matters more than the tool. A valid generator should produce plain Markdown that follows this specification. PRs for more language support are welcome.

1.5 API Location

The well-known path is always at the origin root.

• If the API is under /api/v1, serve /.well-known/skills.md at the same origin. In the file, state that the API base is /api/v1.
• If the API is on https://api.example.com, serve https://api.example.com/.well-known/skills.md.
• If the main site is https://www.example.com, it may link to the API origin. The API origin should still publish its own skills file.
• If the product is a CLI or private repo, keep SKILLS.md next to the code. A checked-in .well-known/skills.md may also help local tools.

2. Well-Known Resources

2.1 Paths

The skills document SHOULD be served at:

/.well-known/skills.md

The JSON discovery document MAY be served at:

/.well-known/mcp.json

2.2 HTTP Methods

• Clients MUST use GET to read either file.
• Clients MAY use HEAD to check if a file exists.
• Servers SHOULD support both GET and HEAD.
• Servers MUST NOT require auth to read these files.

2.3 Content Type

• skills.md SHOULD use text/markdown; charset=utf-8.
• skills.md MAY use text/plain; charset=utf-8.
• mcp.json MUST use application/json or application/json; charset=utf-8.

2.4 Caching

Servers SHOULD send cache headers such as ETag, Last-Modified, and Cache-Control.

3. Skills Document

The skills document tells agents how to work with a site or API.

It should be short. It should use plain words. It should avoid marketing copy.

A skills document for a public API SHOULD include:

• The API name and purpose
• The API base URL or base path
• Auth rules
• Safe read actions
• Risky write actions
• Rate limits or abuse rules, if known
• Links to OpenAPI, MCP, docs, or support
• A clear note that secrets must not be placed in the file

4. JSON Discovery Document

The JSON file is optional. Use it when clients need structured endpoint data.

If present, /.well-known/mcp.json MUST be a JSON object with an mcp object.

{
  "mcp": {
    "spec_version": "2026-06-13",
    "status": "stable",
    "servers": [],
    "tools": []
  }
}

The mcp object MUST include spec_version and status. It MAY include spec_url, skills_url, notes, contact, servers, and tools.

Clients MUST ignore unknown fields.

5. Processing Model

1. Fetch /.well-known/skills.md.
2. Read the safety rules and API base path.
3. Fetch /.well-known/mcp.json only if structured data is needed.
4. Check auth, origin, and user consent before any call.
5. Prefer read-only actions unless the user asks for a write.

A client MUST use HTTPS in production. It MUST NOT require mcp.json if skills.md gives enough guidance.

6. Cross-Origin Rules

Each host is its own origin. Clients SHOULD prefer same-origin APIs.

If a file points to another origin, the client SHOULD show that origin to the user and ask before write actions.

7. Security Rules

These files MUST NOT contain API keys, tokens, passwords, private keys, session ids, or customer secrets.

Auth fields may explain how auth works. They must not include real credentials.

The skills document SHOULD state which actions are safe. Write actions, deletes, purchases, emails, and admin tasks usually need user approval.

Only enable CORS if browser clients need it. Do not use broad CORS to expose private data.

8. IANA Notes

This specification does not request IANA action. If this pattern later becomes a formal standard, skills.md and mcp.json may need well-known URI registration.

9. References

• RFC 2119: Key words for requirement levels
• RFC 8174: Uppercase and lowercase requirement words
• RFC 8259: JSON
• RFC 8615: Well-Known URIs
• Model Context Protocol
• Recommended generator: autoskill-md

Appendix A: Complete Example

/.well-known/skills.md

# Skills

This API lets agents read repair ticket status.

## API

- Base URL: https://tracker.example.com/api/v1
- Public reads: ticket status by ticket id
- Writes: admin only

## Auth

- Public status reads do not need auth.
- Customer actions need a bearer token.
- Do not put tokens in prompts, logs, or this file.

## Safety

- Ask before changing a ticket.
- Do not guess a customer id.
- Stop after three failed auth attempts.

## More Info

- JSON discovery: /.well-known/mcp.json
- Docs: https://tracker.example.com/docs

/.well-known/mcp.json

{
  "mcp": {
    "spec_version": "2026-06-13",
    "spec_url": "https://colinknapp.com/specs/skill-discovery.html",
    "skills_url": "https://tracker.example.com/.well-known/skills.md",
    "status": "stable",
    "notes": "Example JSON discovery file. This file must not contain secrets.",
    "contact": "https://tracker.example.com/support",
    "servers": [],
    "tools": [
      {
        "name": "repair-tracker",
        "description": "Repair ticket status API",
        "url": "https://tracker.example.com/api/v1",
        "capabilities": ["ticket-status"],
        "methods": ["GET"],
        "content_types": ["application/json"],
        "auth": {
          "type": "bearer"
        }
      }
    ]
  }
}

Appendix B: JSON Schema

JSON Schema 2020-12 for /.well-known/mcp.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://colinknapp.com/specs/mcp-discovery.schema.json",
  "title": "Agent Skill JSON Discovery Document",
  "type": "object",
  "required": ["mcp"],
  "properties": {
    "mcp": {
      "type": "object",
      "required": ["spec_version", "status"],
      "properties": {
        "spec_version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
        "spec_url": { "type": "string", "format": "uri" },
        "skills_url": { "type": "string", "format": "uri" },
        "status": { "type": "string", "enum": ["stable", "experimental"] },
        "notes": { "type": "string" },
        "contact": { "type": "string" },
        "servers": { "type": "array" },
        "tools": { "type": "array" }
      }
    }
  }
}