.well-known Skills for API Discovery

How public APIs can publish simple agent instructions at /.well-known/skills.md, with optional JSON discovery at /.well-known/mcp.json.

Update (2026-06-13): The current pattern is SKILLS-first. If a site has an internet-facing API, publish /.well-known/skills.md. Use /.well-known/mcp.json only when a client needs structured endpoint data.

This project recommends github.com/Leopere/autoskill-md for generating Markdown skills files. Other tools can produce the same output. Pull requests for more language support are welcome.

• Summary: Defines a clear well-known place for agent API instructions
• Key outcome: Makes API use safer by giving agents simple rules first
• Tech stack: Web Standards, Markdown, JSON, REST APIs, MCP
• Result: A small pattern that works for APIs, subpaths, subdomains, and repos

The Challenge

Many web services expose APIs. Agents can call those APIs, but they need clear rules.

Those rules are often spread across docs, code, route files, and README files. That makes agents guess. Good agents should not guess where writes are safe, how auth works, or which base path to use.

The .well-known directory is a standard place for site metadata. It gives us a stable URL for agent instructions.

The Approach

Publish a short Markdown file:

/.well-known/skills.md

That file should explain what the API does, the base URL, auth rules, safe actions, risky actions, and links to more docs.

If structured discovery is useful, also publish:

/.well-known/mcp.json

The Markdown file is the first stop. The JSON file is optional.

Autoskill Generation

A team can write skills.md by hand. It can also generate it.

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

The file format matters more than the tool. Other generators are welcome if they make the same plain Markdown contract. PRs for more languages are welcome.

When the API is not at /

The well-known path belongs at the origin root.

• Subpath API: If the API is https://example.com/api/v2, publish https://example.com/.well-known/skills.md and state that /api/v2 is the base path.
• API subdomain: If the API is https://api.example.com, publish https://api.example.com/.well-known/skills.md.
• Parent site: https://www.example.com may link to the API origin, but the API origin should still publish its own file.
• CLI or private repo: Keep SKILLS.md near the code. A checked-in .well-known/skills.md can help local tools.

Example

# 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

The optional JSON file can then stay small:

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

Security Rules

• Use HTTPS in production.
• Do not put secrets in skills.md or mcp.json.
• Say which actions are read-only.
• Say which actions need user approval.
• Treat cross-origin write actions as higher risk.
• Keep CORS narrow unless public browser clients need broad read access.

Specification

The specification lives at Agent Skill Discovery via Well-Known URI. It defines the SKILLS-first pattern and treats mcp.json as optional structured discovery.

Results

This pattern gives agents a clear first step. They can read a short file, learn the API base path, follow safety rules, and avoid guessing.

It also keeps the door open for richer clients. If a client needs machine-readable endpoint data, it can read /.well-known/mcp.json after it reads the skills file.