> ## 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.

# Skillset Governance

> Control who can read and edit skillsets, track revisions and revert changes, and review proposed skill updates

Skillsets are shared organizational knowledge, so they carry access control, full revision history, and a review queue for proposed changes.

## Access Control

Each skillset has an **access mode**:

| Access mode    | Who can see it                                |
| -------------- | --------------------------------------------- |
| `organization` | Everyone in the organization                  |
| `restricted`   | Only principals with an explicit access grant |

For a restricted skillset, you manage **access grants**. Each grant targets a principal and confers a level:

* **Principal type** — `organization`, `group`, or `user`
* **Access level** — `read` or `write`

Any given viewer resolves to an **effective access** of `none`, `read`, or `write`. Effective access is what actually governs the UI and API; it's the value to check when someone reports they can't see or edit a skillset.

<Tip>
  Grants are upserted, so re-granting to the same principal updates the existing grant rather than stacking duplicates. To remove access, delete the grant — don't try to override it with a lower one.
</Tip>

## Revision History

Every skill carries a numbered revision history. You can:

* **List revisions** for a skill
* **Retrieve a specific revision** and read its content as it existed then
* **Revert to a revision**, restoring that content

Reverting is a normal forward-moving edit — it creates new history rather than erasing what happened in between, so the record of what the skill said and when stays intact.

## Proposed Skill Updates

Skills can receive **update suggestions** rather than being edited directly. This is how a skill stays current without any agent silently rewriting your organization's shared instructions.

Each suggestion carries:

| Field                 | Meaning                                                |
| --------------------- | ------------------------------------------------------ |
| `sourceType`          | Where it came from — `mcp_agent` or `automatic_signal` |
| `sourceEvidence`      | What prompted the suggestion                           |
| `patchFormat`         | Always `unified_diff`                                  |
| `baseRevisionVersion` | The revision the patch was written against             |
| `proposedBy`          | The user the proposal is attributed to                 |
| `reviewedBy`          | Who acted on it, once reviewed                         |

### Statuses

| Status       | Meaning                                              |
| ------------ | ---------------------------------------------------- |
| `open`       | Awaiting review                                      |
| `accepted`   | Applied to the skill                                 |
| `rejected`   | Declined                                             |
| `superseded` | No longer applicable — the skill moved on beneath it |

Because a suggestion is a diff against a specific `baseRevisionVersion`, a suggestion written against an older revision can become **superseded** when the skill changes underneath it. That's expected, not a failure: it means the proposal was reasoning about content that no longer exists.

<Warning>
  Review the diff, not just the summary. Suggestions are patches against a specific base revision, and accepting one applies that patch — so a stale suggestion is exactly the case worth reading carefully.
</Warning>

## Activity and Usage

Two separate views answer two different questions:

* **Skill activity** — what happened *to* the skill: edits, reverts, review actions.
* **Skill uses** — when the skill was actually *read*, and by whom.

Usage data is the honest signal about whether a skill earns its place in the catalog. A skill with a rich edit history and no reads is one somebody maintains and nobody consults.

<Note>
  Both activity and use records are attributed to user principals.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Skillsets" icon="book" href="./skillsets">
    Building the catalog and distributing it through MCP.
  </Card>

  <Card title="Knowledge Overview" icon="brain" href="./overview">
    How Knowledge fits together.
  </Card>
</CardGroup>