Skills

Drop SKILL.md files into your project. The agent discovers and uses them for specialized workflows.

Skills are reusable instruction sets. Each skill lives in a folder inside your workspace at .agents/skills/[name]/SKILL.md. The agent loads them when the task matches.

Structure

Create a folder under .agents/skills/ with the skill name, and add a SKILL.md file inside it.

your-workspace/
└── .agents/
    └── skills/
        └── code-review/
            └── SKILL.md

SKILL.md format

YAML frontmatter for the name and description, followed by markdown instructions.

---
name: code-review
description: Review code for bugs, style issues, and best practices
---

# Code Review

When reviewing code, focus on:
- Bug detection
- Performance issues
- Security vulnerabilities

Follow the project's coding conventions.

name is the unique identifier. description tells the agent when to use the skill. Everything after the frontmatter is markdown instructions injected into the conversation when the skill is loaded.

Skill management

Skills can be managed in two ways:

  1. File-based: create and edit .agents/skills/[name]/SKILL.md files directly
  2. Agent-managed: enable the Skills capability in Workspace Settings, and the agent can create, update, and patch skills using the skill_manage tool

When the Skills capability is enabled with a risk level, the agent asks for approval before modifying skills based on the risk threshold.

Per-preconfig scoping

Preconfigs can limit which skills are available. Leave the skills field empty to use all available skills in the workspace, or pick specific ones.

What's next