---
name: create-skill
description: Create new agent skills following the agentskills.io specification. Use when an agent needs a new reusable skill with instructions, scripts, references, or assets.
allowed-tools: create_skill list_skills escalate
---

# Create Skill

You are creating a new agent skill that follows the [Agent Skills specification](https://agentskills.io/specification). A skill is a reusable package of instructions, scripts, and resources that any agent in the network can invoke.

## Skill directory structure

Every skill is a directory containing at minimum a `SKILL.md` file:

```
skill-name/
├── SKILL.md          # Required: YAML frontmatter + markdown instructions
├── scripts/          # Optional: executable code the agent can run
├── references/       # Optional: extended documentation loaded on demand
├── assets/           # Optional: templates, schemas, static resources
```

## SKILL.md format

The file must have YAML frontmatter followed by markdown body content.

### Required frontmatter fields

| Field         | Constraints                                                                          |
|---------------|--------------------------------------------------------------------------------------|
| `name`        | 1-64 chars. Lowercase letters, numbers, hyphens only. Must match directory name.     |
| `description` | 1-1024 chars. Describe what the skill does AND when to use it. Include keywords.     |

### Optional frontmatter fields

| Field           | Purpose                                                              |
|-----------------|----------------------------------------------------------------------|
| `license`       | License name or reference to bundled LICENSE file.                   |
| `compatibility` | Environment requirements (required tools, network access, etc).      |
| `metadata`      | Arbitrary key-value pairs (author, version, etc).                    |
| `allowed-tools` | Space-delimited list of pre-approved tools the skill may use.        |

### Name rules

- Lowercase alphanumeric and hyphens only (`a-z`, `0-9`, `-`)
- Must NOT start or end with a hyphen
- Must NOT contain consecutive hyphens (`--`)
- Must match the parent directory name exactly

### Body content

The markdown body after frontmatter contains skill instructions. Recommended sections:
- Step-by-step procedures
- Examples of inputs and outputs
- Common edge cases and how to handle them

Keep the main SKILL.md under 500 lines. Move detailed reference material to `references/`.

## Progressive disclosure

Skills are loaded in stages to conserve context:
1. **Metadata** (~100 tokens): `name` and `description` are loaded at startup for all skills
2. **Instructions** (< 5000 tokens recommended): Full SKILL.md body loaded when the skill activates
3. **Resources** (as needed): Files in `scripts/`, `references/`, `assets/` loaded only when required

## Scripts

The `scripts/` directory holds executable code the agent can run. Scripts should:
- Be self-contained or clearly document dependencies
- Include helpful error messages
- Handle edge cases gracefully

You may use the project's CLI coder of choice to create scripts. Common languages: Python, Bash, JavaScript. The CLI coder can generate and test scripts within the skill directory.

## References

The `references/` directory holds documentation agents can read on demand:
- `REFERENCE.md` for detailed technical reference
- Domain-specific files (`api.md`, `schemas.md`, etc.)

Keep individual reference files focused. Agents load these on demand so smaller files reduce context usage.

## Assets

The `assets/` directory holds static resources: templates, schemas, configuration files, lookup tables.

## Procedure

1. **Check existing skills first.** Use `list_skills` to see what already exists. Do not create duplicates.
2. **Design the skill.** Decide on name, description, which tools it needs, and what instructions to include.
3. **Create the skill.** Use `create_skill` with the name, description, instructions, and allowed-tools.
4. **Add scripts/references/assets as needed.** Use the project's CLI coder to create any scripts or additional files the skill requires.
5. **Escalate if blocked.** If you are unsure about the skill's scope, tools, or naming — escalate to your parent agent for guidance rather than guessing.

## When to escalate

- The skill overlaps significantly with an existing skill
- The skill requires tools that are not currently registered
- The skill's scope is unclear or could conflict with another agent's domain
- You need approval for the skill's allowed-tools list