Skillset Governance

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

​

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:

​

Statuses

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.

​

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.

​

Next