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 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 ```yaml --- 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: ```bash 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: ```markdown 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: ```bash 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.