Connect an agent to your team’s Skills Board.

Skills Board is a web app for the AI skills a team recommends, and its programmatic surface is a Model Context Protocol server. An agent that authenticates against it can search the team's saved skills and collections, fetch install commands, inspect a GitHub repository for skills, and, with write access, save skills and organize collections.

This page is the whole contract: what is public, how to authenticate, what the tools do, and how the surface behaves when something goes wrong. Everything on it is also machine readable: append .md to this URL, or send Accept: text/markdown, for the same document as Markdown.

The public surface

Everything below is public and needs no credential to fetch, except the MCP endpoint itself. Anything under /api that is not listed here backs the web UI on a session cookie and is not an integration point: it can change without notice.

Connect an agent

Any MCP client that speaks streamable HTTP and can run an OAuth authorization code flow connects without a manually issued key: the server registers the client itself (RFC 7591) the first time it asks.

1. Point the client at https://www.skillsboard.sh/api/mcp as a streamable HTTP MCP server.
2. Let the client discover authentication: an unauthenticated call answers 401 with a WWW-Authenticate header naming the protected resource metadata.
3. The client registers itself dynamically, then runs authorization code + PKCE. A person approves the scopes in a browser; nothing is issued without that approval.
4. Call tools/list on the live session for the tool schemas, then tools/call.

{
  "mcpServers": {
    "skills-board": {
      "type": "http",
      "url": "https://www.skillsboard.sh/api/mcp"
    }
  }
}

The client identifier the registry knows this server by is io.github.TommyBez/skillsboard. A client that cannot run the flow itself can still read every discovery document above, none of which needs a credential.

Tools

The live session is the source of truth for tool schemas; this is the list and what each one needs. A tool marked skills:write is refused by a token that was granted read access only.

Authentication and scopes

Access is user-delegated: a token acts for the person who approved it and reaches exactly the team libraries they belong to. Tokens are audience-bound to the MCP endpoint, so a token minted for another resource is refused.

Revoking a client in Skills Board invalidates its tokens immediately; the next call answers 401 and the client is expected to run the flow again rather than retry.

The registration, authorization, and revocation flow, written for an agent to follow step by step: auth.md.

Versioning and deprecation

The current version of the HTTP surface is 1. Every response carries it in Skills-Board-Api-Version, and a request may send the same header to pin the version it was written against. Supported today: 1. A pinned version this deployment does not serve is refused with 400 and the unsupported_api_version problem rather than answered with a different one.

The paths are deliberately unversioned. The MCP endpoint is the audience every issued token is bound to, and the well-known documents live where their specifications put them; moving either into a /v1 prefix would invalidate tokens and break spec-driven discovery. The version travels in the header instead.

Within a version, members are added but never removed or retyped, and a tool never changes what it does under the same name. A breaking change ships as the next version, and both versions answer until the older one is withdrawn.

A withdrawal is announced on the affected responses with Deprecation and Sunset headers at least 90 days before the sunset date, and the same dates appear on this page. Nothing is removed without that notice.

Deprecation policy

Nothing in the table above is withdrawn without notice. When an operation, a member, or a header is going away, every response it still serves carries Deprecation (RFC 9745) with the date the withdrawal was announced and Sunset (RFC 8594) with the date it stops answering.

The gap between those two dates is never less than 90 days. Until the sunset date the operation answers normally; after it, the path is gone and a request to it gets the ordinary 404.

A client that wants to be warned early should read both headers on every response and treat their appearance as work to schedule, not as an error. The same policy is stated in the OpenAPI description under info.x-deprecation-policy, which names this section, the notice period, and the two headers.

Errors

Failures are typed, and the type is what a client should branch on. The MCP endpoint reports failures the way JSON-RPC does, including 401 and 403, which carry a JSON-RPC error object with a numeric code. Every other endpoint answers with an RFC 9457 problem document under application/problem+json.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 37
RateLimit: "public";r=0;t=37

{
  "type": "https://www.skillsboard.sh/developers#error-rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This client has spent its request budget for the current window. Wait for the window named in Retry-After, then retry.",
  "instance": "https://www.skillsboard.sh/api/health",
  "code": "rate_limited",
  "retry_after": 37
}

The type member is a URL that resolves to the section of this page describing that failure, so a client meeting an unfamiliar code can fetch the explanation instead of parsing the prose. title and detail are written for people and may be reworded; code and status are the stable pair.

The MCP endpoint never answers with a problem document, including for the two refusals it makes before a request reaches the protocol: a pinned version it does not serve (400) and a spent budget (429). Both come back as JSON-RPC error objects, because that is the one body shape an MCP client parses, and both carry the same code from the table above in error.data.code, with retry_after beside it on a 429.

Rate limits

The budgeted endpoints publish what a client has left. The policy is 120 requests per 60 seconds per client per endpoint, and 600 per 60 seconds on the MCP endpoint, counted over a sliding window.

It is counted per serving instance rather than globally, so the numbers are a floor: a client that stays inside them is never refused, and a client spread across instances may get more. That is the honest reading of the headers, and it is the reading an agent needs to pace itself.

A refused request answers 429 with Retry-After. Retrying before the window rolls over is refused again, and the refusal is not charged to the budget.

Clients are counted by the address the platform reports. A request that arrives without one is not counted against anybody, and its response states the policy without a remaining count rather than pooling every such caller into one bucket they could spend for each other.

The discovery documents are served from cache and carry no budget.

Markdown, for reading rather than parsing

Every public page on this site has a Markdown twin at the same URL with a .md suffix, and the page URL itself returns Markdown when the request sends Accept: text/markdown. Those responses carry an x-markdown-tokens header estimating the document's size, so a client can budget a read before it makes it.

Start at https://www.skillsboard.sh/llms.txt, which indexes every page, document, and endpoint this site publishes.

Status, support, and source

• Deployment liveness: HTTP liveness of this deployment. Backing services are not probed.
• Open an issue: Bugs, integration questions, and requests for the MCP surface.
• Source: The whole app, MIT licensed, including every endpoint on this page.
• Contact: For anything that does not belong in a public issue.