skill-forge

Skill Forge — Ultimate Claude Code Skill Creator

Build production-grade Claude Code skills following the Agent Skills open standard, progressive disclosure architecture, and battle-tested patterns from high-performing skills like claude-seo and claude-ads.

Quick Reference

| Command | What it does | |---------|-------------| | /skill-forge | Interactive skill creation wizard | | /skill-forge plan <domain> | Architecture and design planning | | /skill-forge build <name> | Scaffold and build a skill from plan | | /skill-forge review <path> | Audit an existing skill for quality | | /skill-forge evolve <path> | Improve skill based on feedback/issues | | /skill-forge eval <path> | Run eval pipeline to test skill quality | | /skill-forge benchmark <path> | Benchmark skill with variance analysis | | /skill-forge publish <path> | Package and prepare for distribution | | /skill-forge convert <path> | Convert skill to Codex/Gemini/Antigravity/Cursor |

Orchestration Logic

Interactive Mode (/skill-forge)

Walk the user through the full skill creation lifecycle:

1. Discovery: Ask about the domain, use cases, and target users
2. Architecture: Determine skill complexity tier and design structure
3. Build: Generate all files following chosen template
4. Review: Validate structure, frontmatter, triggers, and quality
5. Eval: Run eval pipeline with assertions and grading
6. Benchmark: Measure pass rate, time, tokens with variance analysis
7. Iterate: Refine based on eval results and feedback

Command Routing

For specific commands, load the relevant sub-skill:

• /skill-forge plan -> skills/skill-forge-plan/SKILL.md
• /skill-forge build -> skills/skill-forge-build/SKILL.md
• /skill-forge review -> skills/skill-forge-review/SKILL.md
• /skill-forge evolve -> skills/skill-forge-evolve/SKILL.md
• /skill-forge eval -> skills/skill-forge-eval/SKILL.md
• /skill-forge benchmark -> skills/skill-forge-benchmark/SKILL.md
• /skill-forge publish -> skills/skill-forge-publish/SKILL.md
• /skill-forge convert -> skills/skill-forge-convert/SKILL.md

Skill Complexity Tiers

Detect the appropriate tier based on user's description:

Tier 1: Single Skill (1 SKILL.md)

• Simple workflow or document generation
• No sub-skills or subagents needed
• Under 200 lines of instructions
• Template: assets/templates/minimal.md

Tier 2: Skill + Scripts (SKILL.md + scripts/)

• Needs deterministic execution (validation, data processing)
• Python/Bash scripts for fragile operations
• Template: assets/templates/workflow.md

Tier 3: Multi-Skill Orchestrator (main + sub-skills)

• Complex domain with multiple distinct workflows
• Main skill routes to specialized sub-skills
• Shared references across sub-skills
• Template: assets/templates/multi-skill.md

Tier 4: Full Ecosystem (orchestrator + sub-skills + agents + scripts)

• Enterprise-grade skill with parallel subagent delegation
• Multiple execution scripts for deterministic tasks
• Industry templates and reference knowledge
• Template: assets/templates/ecosystem.md

Core Principles (Enforce in ALL generated skills)

1. Progressive Disclosure (3 Levels)

• Level 1 (frontmatter): Always in system prompt. Name + description only (~50-100 tokens)
• Level 2 (SKILL.md body): Loaded on activation. Core instructions (<500 lines, <5000 tokens)
• Level 3 (references/scripts/assets): Loaded on-demand. Detailed knowledge and execution

2. Description is King

The description field determines when the skill activates. It MUST contain:

• WHAT the skill does (capabilities)
• WHEN to use it (trigger phrases users would say)
• Key domain keywords for matching

Read references/description-guide.md for the complete framework.

3. The 3-Layer Architecture

• Layer 1 (Directive): SKILL.md instructions, reference files = the "what"
• Layer 2 (Orchestration): Claude's routing and decision-making = the "how"
• Layer 3 (Execution): Scripts in scripts/ = the "do"

Push deterministic work into scripts. Keep probabilistic decisions in instructions.

4. Naming Conventions

• Skill folder: kebab-case (lowercase + hyphens only)
• Name field must match folder name exactly
• Sub-skills: {parent}-{child} (e.g., seo-audit, ads-google)
• Agents: agents/{skill}-{role}.md (e.g., agents/seo-technical.md)
• No "claude" or "anthropic" in skill names (reserved)

5. File Rules

• Required: SKILL.md (exact case)
• No README.md inside skill folders
• No XML angle brackets in frontmatter
• Reference files: focused, small, loaded on-demand
• Scripts: atomic, testable, well-documented

Quality Gates

Before marking any generated skill as complete:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] Name is valid kebab-case (1-64 chars)
• [ ] Description includes WHAT + WHEN + keywords (<1024 chars)
• [ ] No XML tags in frontmatter
• [ ] Instructions are specific and actionable (not vague)
• [ ] Error handling included for common failures
• [ ] Examples provided for key workflows
• [ ] SKILL.md body under 500 lines
• [ ] Reference files linked (not inlined) for detailed knowledge
• [ ] Scripts have docstrings, type hints, error handling

Run python scripts/validate_skill.py <path> to verify programmatically.

Reference Files

Load on-demand as needed -- do NOT load all at startup:

• references/anatomy.md -- Skill file structure, naming rules, agent format
• references/patterns.md -- Proven workflow patterns with examples
• references/frontmatter-spec.md -- YAML frontmatter specification (skills)
• references/description-guide.md -- Writing trigger-optimized descriptions
• references/testing-guide.md -- Testing methodology and checklist
• references/pro-agent.md -- 3-layer architecture deep dive
• references/tools-reference.md -- All tool names, permission patterns, MCP
• references/hooks-reference.md -- Hook events, types, quality gate patterns
• references/skills-activation.md -- Skill discovery, activation, advanced features
• references/platforms.md -- Platform specs and conversion rules

Sub-Skills

This skill orchestrates 8 specialized sub-skills:

1. skill-forge-plan -- Architecture design and use case planning
2. skill-forge-build -- Scaffold and generate skill files
3. skill-forge-review -- Audit and validate existing skills
4. skill-forge-evolve -- Improve skills based on feedback
5. skill-forge-eval -- Run eval pipeline with assertions and grading
6. skill-forge-benchmark -- Benchmark performance with variance analysis
7. skill-forge-publish -- Package and prepare for distribution
8. skill-forge-convert -- Convert skills for Codex, Gemini CLI, Antigravity, Cursor