---

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. 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