> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skillsets

> Build an organization-wide catalog of agent skills and distribute it to any AI client through MCP

Skillsets (`/knowledge/skillsets`) are BuildBetter's organization-wide catalog of **agent skills** — reusable Markdown instructions that any teammate's AI agent can find and read without cloning a repository, installing a CLI, or knowing an internal file path.

A **skillset** is a named collection. A **skill** is one piece of Markdown content inside exactly one skillset.

<Info>
  Skillsets requires the organization-level `skillsets` feature flag.
</Info>

## Why It Exists

BuildBetter already tracked skills installed in connected code repositories. Skillsets solves a different problem: a marketing, GTM, support, or product teammate needs the same current instructions an engineer has, and shouldn't need developer tooling to get them.

By exposing the catalog through [BuildBetter MCP](../MCP/tool-reference), any authenticated agent — Claude, ChatGPT, Cursor, or anything else that speaks MCP — can discover and read your skills. BuildBetter serves the content; the client decides how to use it.

## Structure

| Concept      | Rules                                                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skillset** | Organization-scoped. Has a display name and a stable slug for filtering. Slugs are unique among active skillsets in an organization.                  |
| **Skill**    | Belongs to exactly one skillset. Has a name, optional description, and full Markdown content. Names are unique among active skills within a skillset. |
| **Position** | Skills carry an integer position, so catalog order is stable and you control it.                                                                      |

Both expose a stable UUID `public_id` through external APIs. Deletion is soft, so removing a catalog entry doesn't immediately destroy history.

## Managing the Catalog

From the Skillsets page you can:

* Create, edit, and delete skillsets
* Create, edit, and delete skills within a set
* Reorder skills (move up / move down)
* Copy a skill's content
* View a selected skill's description and full rendered content

<Tip>
  Order is not cosmetic. Agents read the catalog in the order you set, so put foundational skills before the ones that build on them.
</Tip>

## Reading Skills from an Agent

Three read-only MCP tools cover discovery and retrieval:

| Tool             | Returns                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `list-skillsets` | Active skillsets for your organization, with skill counts and skill summaries — no full content |
| `list-skills`    | Skill summaries, filterable by skillset UUID, name or slug, and an optional text phrase         |
| `get-skill`      | One skill's complete Markdown content, plus its parent skillset context                         |

All three are annotated read-only, idempotent, and non-destructive.

Two behaviors worth knowing:

* **Empty is not an error.** No matches returns structured JSON with `total: 0` and an empty array.
* **Cross-organization existence never leaks.** A missing or inaccessible id returns a not-found style error that doesn't reveal whether the id exists in some other organization.

<Note>
  MCP reads are scoped to the authenticated principal's organization and never call external source providers live. The catalog you read is the catalog stored in BuildBetter.
</Note>

## What Skillsets Is Not

* **Not repository skills.** Skillsets are a separate, organization-scoped model from skills installed in a connected code repository. The two are not unified.
* **Not synced from GitHub.** External source configuration, sync, pull-request writeback, and version proposal workflows are deferred. There is no source to configure.
* **Not auto-generated.** BuildBetter does not invent skills from your signals or rewrite them on its own. Changes are proposed and reviewed — see [Skillset Governance](./skillset-governance).
* **Not installed into your AI client.** MCP exposes the content; the client decides what to do with it.

## Next

<CardGroup cols={2}>
  <Card title="Skillset Governance" icon="shield-check" href="./skillset-governance">
    Access control, revision history, and reviewing proposed skill updates.
  </Card>

  <Card title="MCP Tool Reference" icon="plug" href="../MCP/tool-reference">
    Every BuildBetter MCP tool, including the skill catalog tools.
  </Card>
</CardGroup>