[Docs index](/docs.md) / [Agent Skills](/docs/agent-skills/overview.md) / Authoring and Approving Agent Skills

---

# Authoring and Approving Agent Skills

This guide explains how to write, edit, submit, and approve Agent Skill versions.

For a mid-sized company standardizing AI usage, approval is the step that turns an informal workflow into an Assist-managed workflow. It gives the team a clear point to check tone, data handling, required review, and whether the agent is being asked to do something it should not do.

## Before you begin

- You need edit access to author a draft.
- The selected version must be a draft before files can be edited.
- Approved, pending, and rejected versions are read-only.
- `/SKILL.md` must exist before a version can be submitted.
- Identify the workflow owner who should approve the first production version.

## Steps

### 1. Open the Agent Skill

Open **Skills**, then select the Agent Skill you want to edit.

The detail page shows the current status, scope, version selector, and tabs for **Overview**, **Files**, **Versions**, and **Usage**.

![Agent Skill detail overview](screenshots/agent-skills-detail-overview.png)

### 2. Create a draft

If the selected version is approved and no draft already exists, click **New Draft**. Assist creates a draft based on the latest approved version.

If **New Draft** is not visible, check whether:

- You do not have edit access.
- A draft already exists.
- The selected version is pending review.

### 3. Open Files

Select **Files**. The file tree appears on the left and the editor appears on the right.

### 4. Write `/SKILL.md` as a managed workflow

Select `/SKILL.md` and write instructions that an Assist agent can follow. For AI usage cleanup, include:

- When the agent should use the skill.
- Which inputs the user must provide.
- Which systems, documents, or examples the agent should inspect.
- The expected output format.
- What the agent should not do.
- When the agent should ask for human review before producing or sending work.

Good skills are specific. Instead of "help sales write follow-ups," write the trigger, required inputs, tone rules, output format, and review conditions.

### 5. Add supporting files

Click the **Add file** icon to add supporting material. Useful files include:

- `/examples/good-output.md`
- `/examples/bad-output.md`
- `/templates/team-summary.md`
- `/policies/customer-data-rules.md`
- `/checklists/review-before-rollout.md`

Supporting files keep `SKILL.md` focused while giving reviewers enough detail to trust the workflow.

### 6. Save changes

Click the save icon. The button is enabled only when the selected file has unsaved changes.

### 7. Submit the draft

Click **Submit**. The draft becomes **Pending** and is read-only while it waits for review.

### 8. Approve or reject

An admin reviews the version.

- **Approve** makes the version available for attachment to agents.
- **Reject** records the reason and keeps the rejected version for history.

## Recommended approval checklist

- The skill names the exact workflow it supports.
- The procedure defines when it should and should not run.
- The procedure does not depend on private prompts that only one employee understands.
- Sensitive data handling is explicit.
- Customer-facing outputs require human review when appropriate.
- The agent is not asked to access systems or take actions it cannot perform.
- The output format is useful to the team receiving the work.

## Next steps

- [Governing Agent Skill Versions](governing-agent-skill-versions.md)
- [Attaching Skills to Operational Agents](attaching-skills-to-operational-agents.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** (current)
- [Creating a Managed AI Workflow Skill](/docs/agent-skills/creating-a-managed-ai-workflow-skill.md)
- [Governing Agent Skill Versions](/docs/agent-skills/governing-agent-skill-versions.md)
- [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)