Create Skill

Create Skill

This skill helps you create new Agent Skills that follow the agentskills.io specification.

When to Use This Skill

Use this skill when the user asks you to:

• Create a new skill or capability
• Package instructions into a reusable format
• Set up a skill directory

Agent Skills Format

An Agent Skill is a directory containing a SKILL.md file with YAML frontmatter:

my-skill/
  SKILL.md

SKILL.md Structure

CRITICAL: When you write SKILL.md, the very first characters in the file must be --- (the YAML frontmatter opening delimiter). Do not write any title, description, or other content before the ---.

---
name: my-skill
description: A clear description of what this skill does and when to use it.
license: (optional)
compatibility: Any environment requirements (optional)
metadata: (optional)
author: your-name
version: '1.0'
---

# Skill Title

## When to Use This Skill

Describe the scenarios where this skill should be applied.

## Instructions

Step-by-step instructions for the agent to follow.

## Examples

Include examples of inputs and expected outputs.

Common mistake: The first line of SKILL.md must be --- (the frontmatter opening delimiter). Do NOT put any title, comment, or blank lines before it.

Frontmatter Requirements

Required fields:

• name: 1-64 characters, lowercase alphanumeric and hyphens only
  • Must match the directory name exactly
  • Cannot start or end with hyphens
  • No consecutive hyphens allowed
  • Valid examples: pdf-processing, code-review, data-analysis
  • Invalid examples: -my-skill, my--skill, My_Skill
• description: 1-1024 characters describing:
  • What the skill does
  • When it should be used (important for agent discovery)
  • Should include specific keywords and trigger phrases

Optional fields:

• license: Licensing terms (e.g., MIT, Apache-2.0)
• compatibility: Environment requirements, max 500 characters
• metadata: Key-value pairs for additional information
• allowed-tools: Space-delimited list of pre-approved tools (experimental)

Instructions for Creating a New Skill

1. Understand the requirement: Ask the user what the skill should accomplish and when it should be used.
2. Choose a name: Pick a descriptive, lowercase name with hyphens for word separation.
3. Write a clear description: This is crucial for skill discovery.
4. Create comprehensive instructions: Write clear, step-by-step guidance.
5. Create the skill directory and file: {skills_dir}/{skill-name}/SKILL.md
6. Validate the skill: pip install -q skills-ref && agentskills validate {skills_dir}/{skill-name}
7. Prepare for sharing: Single-file skill: share SKILL.md directly. Multi-file: create a .zip archive.
8. Inform the user: Let the user know the skill has been created and validated successfully.

Common Errors

Error: "SKILL.md must start with YAML frontmatter (---)"

• File doesn't start with --- on line 1
• Wrong: Starting with title # My Skill before ---
• Correct: File starts immediately with ---

Error: Invalid name format

• Must be 1-64 characters
• Lowercase letters, numbers, and hyphens only
• Cannot start or end with hyphen
• No consecutive hyphens (--)