Skill Generator

Generate new skills with proper format, structure, and conventions. This meta-skill helps agents create skills without hallucinating the format.

Quick Start

To generate a new skill:

bash scripts/generate-skill.sh <skill-name> [target-directory]

This creates a complete skill scaffold with:

• •SKILL.md with proper frontmatter
• •scripts/ directory for executable helpers
• •references/ directory for documentation
• •Placeholder content following conventions

Skill Format Conventions

Every skill MUST include:

1. •

   SKILL.md (required) - Main skill file with:

   • •YAML frontmatter (name, description)
   • •Markdown body with instructions
2. •

   Bundled Resources (optional):

   • •scripts/ - Executable code (bash/python/etc)
   • •references/ - Documentation loaded on-demand
   • •assets/ - Files used in output (templates, etc)

Frontmatter Requirements

---
name: skill-name
description: What the skill does AND when to use it. Include triggering scenarios.
---

The description field is critical for skill discovery and triggering. Include:

• •What the skill does
• •When to use it (specific triggers)
• •What contexts activate it

Directory Structure

skill-name/
├── SKILL.md (required)
├── scripts/ (optional)
│   └── example-script.sh
├── references/ (optional)
│   └── conventions.md
└── assets/ (optional)
    └── template-file

Writing Effective Skills

Keep SKILL.md Lean

Target <500 lines in SKILL.md. Move detailed content to references/:

• •Core workflow → SKILL.md
• •Detailed examples → references/
• •API docs → references/
• •Long explanations → references/

Use Imperative Form

Write instructions as commands:

• •"Read the file first" ✓
• •"You should read the file" ✗
• •"Check for patterns" ✓
• •"Consider checking patterns" ✗

Progressive Disclosure

Skills use three-level loading:

1. •Metadata (~100 words) - Always in context
2. •SKILL.md body (<5k words) - When skill triggers
3. •Bundled resources (unlimited) - Loaded as needed

Bundled Resources

scripts/

Executable code for deterministic tasks:

• •When the same code is rewritten repeatedly
• •When reliability is critical
• •Run via bash/python without loading to context

Make scripts executable:

chmod +x scripts/my-script.sh

references/

Documentation loaded on-demand:

• •Database schemas
• •API documentation
• •Detailed workflow guides
• •Domain knowledge

Keep reference files focused. For files >100 lines, include a table of contents.

Reference from SKILL.md with clear guidance on when to read:

See references/api-docs.md for complete API reference.

assets/

Files used in output (not loaded to context):

• •Templates
• •Images/icons
• •Boilerplate code
• •Fonts/typography

What NOT to Include

Do NOT create these files:

• •README.md
• •INSTALLATION_GUIDE.md
• •QUICK_REFERENCE.md
• •CHANGELOG.md

Skills should contain only what an AI agent needs to execute the task. No auxiliary documentation.

Validation

Before finalizing, validate the skill:

bun scripts/validate-skill.ts path/to/skill

Checks:

• •YAML frontmatter format
• •Required fields present
• •No TODO placeholders
• •No extraneous files
• •Naming conventions

Reference

See references/conventions.md for complete skill format specification.