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