Create skill

Create Skill

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

Quick Start

When asked to create a new skill:

1. Gather requirements: Ask what the skill should do
2. Choose a name: lowercase letters, numbers, hyphens only (e.g., pdf-processing, data-analysis)
3. Generate the structure: Create SKILL.md with proper frontmatter
4. Add optional components: scripts, references, assets as needed

Directory Structure

skill-name/
├── SKILL.md          # Required: main skill file
├── scripts/          # Optional: executable code
├── references/       # Optional: additional documentation
└── assets/           # Optional: static resources

SKILL.md Template

---
name: your-skill-name
description: What this skill does and when to use it. Be specific and include keywords that help agents identify relevant tasks. Max 1024 characters.
license: MIT
compatibility: Optional - environment requirements if any
metadata:
  author: your-name
  version: "1.0"
allowed-tools: Optional - pre-approved tools (experimental)
---

# Skill Title

Brief introduction to the skill.

## Usage

Step-by-step instructions on how to use this skill.

## Examples

Example inputs and outputs.

## Notes

Common edge cases and tips.

Field Requirements

name (required)

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• Cannot start or end with -
• No consecutive hyphens --
• Must match directory name

Valid: pdf-processing, data-analysis, code-review-2 Invalid: PDF-Processing, -pdf, pdf--processing

description (required)

• 1-1024 characters
• Describe WHAT the skill does AND WHEN to use it
• Include specific keywords for discoverability

Good: "Extracts text and tables from PDF files. Use when working with PDF documents, extracting content from PDFs, or processing scanned documents." Poor: "Helps with PDFs."

license (optional)

• License name or reference to bundled license file
• Examples: MIT, Apache-2.0, Proprietary. LICENSE.txt has complete terms

compatibility (optional)

• 1-500 characters
• Only include if skill has specific environment requirements
• Examples: "Requires Python 3.8+ and pandas", "Needs internet access for API calls"

metadata (optional)

• Arbitrary key-value pairs
• Common keys: author, version, tags

allowed-tools (optional, experimental)

• Space-delimited list of pre-approved tools
• Example: Bash(git:*) Bash(jq:*) Read

Best Practices

Progressive Disclosure

Design for efficient context usage:

1. Metadata (~100 tokens): Loaded at startup for all skills
2. Instructions (<5000 tokens recommended): Loaded when skill is activated
3. Resources: Loaded on-demand

Keep SKILL.md under 500 lines. Move detailed content to references/.

File Organization

• Keep SKILL.md focused on core instructions
• Put detailed docs in references/REFERENCE.md
• Put templates in assets/
• Put executable code in scripts/

File References

Use relative paths from skill root:

See [the reference guide](references/REFERENCE.md) for details.
Run: scripts/process.py

Keep references one level deep. Avoid deeply nested chains.

Validation

After creating a skill, validate it:

# Install skills-ref if needed
npm install -g @agentskills/skills-ref

# Validate the skill
skills-ref validate ./your-skill-name

Workflow Example

When asked to create a skill for X:

1. Create directory: your-skill-name/
2. Write SKILL.md with:
   • Proper frontmatter (name, description)
   • Clear instructions in Markdown body
3. Optionally add:
   • scripts/ for helper scripts
   • references/ for detailed docs
   • assets/ for templates/data
4. Validate with skills-ref validate
5. Test the skill with an agent

Common Patterns

Simple Skill

Just a SKILL.md with instructions:

my-skill/
└── SKILL.md

Skill with Scripts

For skills that run code:

my-skill/
├── SKILL.md
└── scripts/
    └── helper.py

Skill with References

For detailed documentation:

my-skill/
├── SKILL.md
└── references/
    ├── REFERENCE.md
    └── examples.md

Full-featured Skill

my-skill/
├── SKILL.md
├── scripts/
│   ├── setup.sh
│   └── process.py
├── references/
│   ├── API.md
│   └── FORMATS.md
└── assets/
    ├── template.json
    └── schema.json

References

• Official Specification
• Documentation Index
• skills-ref Validator