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 draftsUpdate support escalation summary formatAdd 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.mdsays 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.
- Create a draft from the best existing prompt or workflow.
- Remove private data and unclear assumptions.
- Submit the draft with a plain-language summary of what changed.
- Have the department owner or workspace admin approve it.
- Attach or upgrade one operational agent first.
- Review real output with the team using the workflow.
- 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.