joelhooks/skill-generator

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.