# skillmd.com auth.md

How agents, CLIs and MCP clients authenticate to SkillMD.

## Who this is for

Automated clients that read the SkillMD registry or publish skills to it on
behalf of a signed-in human: coding agents, the `skillmd` CLI, MCP clients,
and scripts.

## Reading is open

Search, listing, skill detail and raw `SKILL.md` downloads need no credentials:

- `https://api.skillmd.com/v1/search?q=<query>`
- `https://api.skillmd.com/v1/skills`
- `https://api.skillmd.com/v1/skills/<owner>/<name>`
- `https://api.skillmd.com/api/skills/<owner>/<name>/raw`

Unauthenticated reads are subject to fair-use limits per client. Requests that
carry a valid token get a higher budget. Sustained bulk downloading is slowed
progressively rather than blocked outright.

## Publishing needs a token

Write operations (publishing, saving, following) require a personal access
token sent as a bearer header:

```
Authorization: Bearer <token>
```

Tokens are issued to a signed-in human from their SkillMD account and are never
issued to an agent directly. A human stores one for the CLI with
`skillmd login` (see https://skillmd.com/docs/cli). Agents should reuse a token the human
has already configured, or ask the human to run `skillmd login`.

Requests without a valid token receive `401` with a `WWW-Authenticate`
header whose `resource_metadata` parameter points at the API's protected
resource metadata below.

## Discovery documents

- Protected resource metadata (web): https://skillmd.com/.well-known/oauth-protected-resource
- Protected resource metadata (API): https://api.skillmd.com/.well-known/oauth-protected-resource
- Authorization server metadata: https://skillmd.com/.well-known/oauth-authorization-server
- OpenID Connect discovery: https://skillmd.com/.well-known/openid-configuration
- API catalog (RFC 9727): https://skillmd.com/.well-known/api-catalog
- OpenAPI: https://skillmd.com/openapi.json
- MCP server card: https://skillmd.com/.well-known/mcp/server-card.json

## What we do not offer

- No agent self-registration or provisioning endpoint. Do not POST to guess
  one; registration would create accounts and is intentionally absent.
- No dynamic client registration at the authorization server.
- The API does not accept the authorization server's access tokens today. The
  authorization server is listed because it is where human identity lives;
  API credentials are the personal access tokens described above.

## Contact

hi@skillmd.com