[Docs index](/docs.md) / [Agent Skills](/docs/agent-skills/overview.md) / Governing Agent Skill Versions

---

# Governing Agent Skill Versions

Use version management to review Agent Skill changes before they affect operational agents. For mid-sized companies cleaning up scattered AI usage, this prevents a useful workflow from turning into an unmanaged prompt collection again.

## Permission levels

| Level | What it allows |
|-------|----------------|
| Read | View the Agent Skill, approved files, and attachment information visible to you. |
| Edit | Create drafts, edit draft files, submit drafts, and attach readable versions when you can edit the target agent. |
| Admin | Approve or reject pending versions and manage the Agent Skill for the workspace. |

## Version states

| State | Meaning |
|-------|---------|
| Draft | Editable version. Use this for writing and testing changes. |
| Pending | Submitted for review. It is read-only until approved or rejected. |
| Approved | Reviewed version that can be mounted for normal agent use. |
| Rejected | Historical version that was not accepted. Create a new draft to continue work. |

## Steps

### 1. Open Versions

Open the Agent Skill and select **Versions**. Each version shows its status, short ID, commit message, and creation time.

### 2. Choose a version

Click a version to inspect it. The version selector at the top also lets you switch between versions.

### 3. Create a new draft

Click **New Draft** from an approved version. Assist forks the latest approved version by default.

Only one open draft can exist at a time for a skill. Finish, delete, or submit the current draft before creating another.

### 4. Submit for review

After saving draft edits, click **Submit**. The draft becomes pending.

Use the commit message to explain the workflow reason for the change, such as:

- `Add review rule for customer-facing AI drafts`
- `Update support escalation summary format`
- `Add examples from sales follow-up cleanup`

### 5. Approve or reject

Admins can approve or reject pending versions.

If rejecting a version, enter a reason that tells the author what to fix. The author can create a new draft from an approved version and apply the feedback.

### 6. Upgrade mounted agents

Approving a version does not automatically change mounted agents. Open **Usage** and click **Upgrade** on any mount that should move to the latest approved version.

## Recommended review checklist

- `SKILL.md` says when the skill should be used.
- The Agent Skill does not ask the agent to use unavailable tools.
- The workflow has clear input requirements.
- Customer-facing or sensitive outputs require human review when appropriate.
- Supporting examples are current and do not contain private data.
- The Agent Skill is scoped correctly as workspace or personal.
- The test agent follows the skill in the expected workflow.

## Rollout pattern for AI cleanup

Use a staged rollout when the skill standardizes a workflow employees already use informally.

1. Create a draft from the best existing prompt or workflow.
2. Remove private data and unclear assumptions.
3. Submit the draft with a plain-language summary of what changed.
4. Have the department owner or workspace admin approve it.
5. Attach or upgrade one operational agent first.
6. Review real output with the team using the workflow.
7. Upgrade additional agents after the output is accepted.

For higher-risk workflows, keep a lightweight release note in a supporting file such as `/release-notes/2026-05-support-summary.md`. Include what changed, who approved it, and which agents should move to the new version.

## Related guides

- [Authoring and Approving Agent Skills](authoring-and-approving-agent-skills.md)
- [Attaching Skills to Operational Agents](attaching-skills-to-operational-agents.md)
- [Use cases and playbooks](use-cases.md)
- [Troubleshooting](troubleshooting.md)

---

## Navigation

### In this section: Agent Skills

- [Agent Skills](/docs/agent-skills/overview.md)
- [Use Cases and Playbooks](/docs/agent-skills/use-cases.md)
- [Troubleshooting Agent Skills](/docs/agent-skills/troubleshooting.md)
- [Attaching Agent Skills to Operational Agents](/docs/agent-skills/attaching-skills-to-operational-agents.md)
- [Authoring and Approving Agent Skills](/docs/agent-skills/authoring-and-approving-agent-skills.md)
- [Creating a Managed AI Workflow Skill](/docs/agent-skills/creating-a-managed-ai-workflow-skill.md)
- **Governing Agent Skill Versions** (current)
- [Importing a Team AI Workflow Skill](/docs/agent-skills/importing-a-team-ai-workflow-skill.md)

#### Playbooks

- [Playbook: Build a Department AI Rollout Skill](/docs/agent-skills/playbook-department-ai-rollout.md)
- [Playbook: Build a Team AI Usage Cleanup Skill](/docs/agent-skills/playbook-ai-usage-inventory.md)
- [Playbook: Build a Team Prompt Standardization Skill](/docs/agent-skills/playbook-prompt-standardization.md)

### Other sections

- [MCP Servers](/docs/mcp-servers/overview.md)
- [Tool Creation](/docs/tool-creation/overview.md)
- [Agent Filesystem](/docs/agent-filesystem/overview.md)
- [Chat Sharing](/docs/chat-sharing/overview.md)
- [Scheduled Triggers](/docs/scheduled-triggers/overview.md)
- [Sandcastles](/docs/sandcastles/overview.md)
- [Subagents](/docs/subagents/overview.md)
- [Workspace Permissions](/docs/workspace-permissions/overview.md)

[Back to docs index](/docs.md)