Skill Creator

This skill provides guidance for creating effective, agent-agnostic skills.

About Skills

Skills are modular, self-contained packages that extend AI agent capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform a general-purpose agent into a specialized agent equipped with procedural knowledge.

What Skills Provide

Specialized workflows - Multi-step procedures for specific domains
Tool integrations - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Core Principles

Concise is Key

The context window is a public good. Skills share context with everything else the agent needs.

Default assumption: The agent is already very smart. Only add context it doesn't already have. Challenge each piece of information: "Does the agent really need this?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Every SKILL.md consists of:

Frontmatter (YAML): Contains name and description fields. These are the only fields read to determine when the skill gets used—be clear and comprehensive.
Body (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers.

Bundled Resources (optional)

Scripts (`scripts/`)

Executable code for tasks that require deterministic reliability or are repeatedly rewritten.

When to include: When the same code is being rewritten repeatedly
Example: scripts/rotate_pdf.py for PDF rotation tasks
Benefits: Token efficient, deterministic

References (`references/`)

Documentation and reference material loaded as needed into context.

When to include: For documentation the agent should reference while working
Examples: references/schema.md for database schemas, references/api_docs.md for API specifications
Benefits: Keeps SKILL.md lean, loaded only when needed

Assets (`assets/`)

Files not intended to be loaded into context, but used within output.

When to include: When the skill needs files for final output
Examples: assets/logo.png for brand assets, assets/template.html for HTML boilerplate

Progressive Disclosure

Skills use a three-level loading system:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - When skill triggers (<5k words)
Bundled resources - As needed (unlimited)

Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit.

Skill Creation Process

Step 1: Understand the Skill

Clarify with concrete examples:

"What functionality should this skill support?"
"Can you give examples of how this skill would be used?"
"What would trigger this skill?"

Step 2: Plan Reusable Contents

Analyze each example:

Consider how to execute from scratch
Identify helpful scripts, references, and assets

Step 3: Create the Skill

Create the skill directory:

skill-name/
├── SKILL.md
├── scripts/     (if needed)
├── references/  (if needed)
└── assets/      (if needed)

Step 4: Write SKILL.md

Frontmatter

---
name: skill-name
description: What the skill does and when to use it. Include specific triggers and contexts. Max 1024 characters.
---

Description guidelines:

Include both what the skill does AND when to use it
Include trigger phrases
Max 1024 characters, no XML tags
Write in third person

Body

Write instructions for using the skill. Include:

Quick start guide
Step-by-step workflow
Links to reference files when needed

Step 5: Test and Iterate

Use the skill on real tasks
Notice struggles or inefficiencies
Update SKILL.md or resources accordingly
Test again

Quality Checklist

Before finalizing:

Description is specific about when to use (max 1024 chars)
Folder name uses kebab-case
Instructions are actionable and unambiguous
Scope is focused (one responsibility)
SKILL.md body < 500 lines
References are one level deep from SKILL.md

Output Messages

When creating a skill, inform the user:

✅ Skill created successfully!

📁 Location: .agent/skills/[name]/SKILL.md
🎯 Purpose: [brief description]
🔧 How to test: [example prompt that should trigger the skill]

💡 Tip: The agent will use this skill automatically when it detects [context].

skill-creator