Skill Factory

Skill Factory

Comprehensive workflow orchestrator for creating high-quality Claude Code skills with automated research, content review, and multi-tier validation.

When to Use This Skill

Use skill-factory when:

• Creating any new skill - From initial idea to validated, production-ready skill
• Research needed - Automate gathering of documentation, examples, and best practices
• Quality assurance required - Ensure skills meet official specifications and best practices
• Guided workflow preferred - Step-by-step progression with clear checkpoints
• Validation needed - Runtime testing, integration checks, and comprehensive auditing

Scope: Creates skills for ANY purpose (not limited to meta-claude plugin):

• Infrastructure skills (terraform-best-practices, ansible-vault-security)
• Development skills (docker-compose-helper, git-workflow-automation)
• Domain-specific skills (brand-guidelines, conventional-git-commits)
• Any skill that extends Claude's capabilities

Available Operations

The skill-factory provides 9 specialized commands for the create-review-validate lifecycle:

Power user tip: Commands work standalone or orchestrated. Use individual commands for targeted fixes, or invoke the skill for full workflow automation.

Visual learners: See workflows/visual-guide.md for decision trees, state diagrams, and workflow visualizations.

Quick Decision Guide

Full Workflow vs Individual Commands

Creating new skill (full workflow):

• With research → skill-factory <skill-name> <research-path>
• Without research → skill-factory <skill-name> (includes firecrawl research)
• From knowledge only → skill-factory <skill-name> → Select "Skip research"

Using individual commands (power users):

When to use full workflow: Creating new skills from scratch When to use individual commands: Fixing specific issues, power user iteration

For full workflow details, see Quick Start section below.

Quick Start

Path 1: Research Already Gathered

If you have research materials ready:

# Research exists at docs/research/skills/<skill-name>/
skill-factory <skill-name> docs/research/skills/<skill-name>/

The skill will:

1. Format research materials
2. Create skill structure (scaffold)
3. Write skill content (synthesize references)
4. Review content quality
5. Review technical compliance
6. Validate runtime loading
7. Validate integration
8. Run comprehensive audit
9. Present completion options

Path 2: Research Needed

If starting from scratch:

# Let skill-factory handle research
skill-factory <skill-name>

The skill will ask about research sources and proceed through full workflow.

Example Usage

User: "Create a skill for CodeRabbit code review best practices"

skill-factory detects no research path provided, asks:

"Have you already gathered research for this skill?
[Yes - I have research at <path>]
[No - Help me gather research]
[Skip - I'll create from knowledge only]"

User: "No - Help me gather research"

skill-factory proceeds through Path 2:
1. Research skill domain
2. Format research materials
3. Create skill structure
... (continues through all phases)

When This Skill Is Invoked

Your role: You are the skill-factory orchestrator. Your task is to guide the user through creating a high-quality, validated skill using 9 primitive slash commands.

Step 1: Entry Point Detection

Analyze the user's prompt to determine which workflow path to use:

If research path is explicitly provided:

User: "skill-factory coderabbit docs/research/skills/coderabbit/"
→ Use Path 1 (skip research phase)

If no research path is provided:

Ask the user using AskUserQuestion:

"Have you already gathered research for this skill?"

Options:
[Yes - I have research at a specific location]
[No - Help me gather research]
[Skip - I'll create from knowledge only]

Based on user response:

• Yes → Ask for research path, use Path 1
• No → Use Path 2 (include research phase)
• Skip → Use Path 1 without research (create from existing knowledge)

Step 2: Initialize TodoWrite

Create a TodoWrite list based on the selected path:

Path 2 (Full Workflow with Research):

TodoWrite([
  {"content": "Research skill domain", "status": "pending", "activeForm": "Researching skill domain"},
  {"content": "Format research materials", "status": "pending", "activeForm": "Formatting research materials"},
  {"content": "Create skill structure", "status": "pending", "activeForm": "Creating skill structure"},
  {"content": "Write skill content", "status": "pending", "activeForm": "Writing skill content"},
  {"content": "Review content quality", "status": "pending", "activeForm": "Reviewing content quality"},
  {"content": "Review technical compliance", "status": "pending", "activeForm": "Reviewing technical compliance"},
  {"content": "Validate runtime loading", "status": "pending", "activeForm": "Validating runtime loading"},
  {"content": "Validate integration", "status": "pending", "activeForm": "Validating integration"},
  {"content": "Run comprehensive audit", "status": "pending", "activeForm": "Running comprehensive audit"},
  {"content": "Complete workflow", "status": "pending", "activeForm": "Completing workflow"}
])

Path 1 (Research Exists or Skipped):

Omit the first "Research skill domain" task. Start with "Format research materials" or "Create skill structure" depending on whether research exists.

Step 3: Execute Workflow Sequentially

For each phase in the workflow, follow this pattern:

1. Mark phase as in_progress

Update the corresponding TodoWrite item to in_progress status.

2. Check dependencies

Before running a command, verify prior phases completed:

• Write requires create to complete (needs skill structure with references)
• Review-content requires write to complete (needs actual content to review)
• Review-compliance requires review-content to pass
• Validate-runtime requires review-compliance to pass
• Validate-integration requires validate-runtime to pass
• Validate-audit runs regardless (non-blocking feedback)

3. Invoke command using SlashCommand tool

/meta-claude:skill:research <skill-name> [sources]
/meta-claude:skill:format <research-dir>
/meta-claude:skill:create <skill-name> <research-dir>
/meta-claude:skill:write <skill-path>
/meta-claude:skill:review-content <skill-path>
/meta-claude:skill:review-compliance <skill-path>
/meta-claude:skill:validate-runtime <skill-path>
/meta-claude:skill:validate-integration <skill-path>
/meta-claude:skill:validate-audit <skill-path>

IMPORTANT: Wait for each command to complete before proceeding to the next phase. Do not invoke multiple commands in parallel.

4. Check command result

Each command returns success or failure with specific error details.

5. Apply fix strategy if needed

The workflow uses a three-tier fix strategy:

• Tier 1 (Simple): Auto-fix formatting, frontmatter, markdown syntax
• Tier 2 (Medium): Guided fixes with user approval
• Tier 3 (Complex): Stop and report - requires manual fixes

One-shot policy: Each fix applied once, re-run once, then fail fast if still broken.

For complete tier definitions, issue categorization, examples, and fix workflows: See references/error-handling.md

6. Mark phase completed

Update TodoWrite item to completed status.

7. Continue to next phase

Proceed to the next workflow phase, or exit if fail-fast triggered.

Step 4: Completion

When all phases pass successfully:

Present completion summary:

✅ Skill created and validated successfully!

Location: <skill-output-path>/

Research materials: docs/research/skills/<skill-name>/

Ask about artifact cleanup:

Keep research materials? [Keep/Remove] (default: Keep)

Present next steps using AskUserQuestion:

Next steps - choose an option:
[Test in new session - Skills require session reload to be discoverable]
[Create PR - Submit skill to repository]
[Done - Exit workflow]

Execute user's choice:

• Test in new session → Skills load at session start. User must restart Claude Code to test.
• Create PR → Create git branch, commit, push, open PR
• Done → Clean exit

Note: Skills auto-discover based on directory structure - no plugin.json registration needed.

Key Execution Principles

Sequential Execution: Do not run commands in parallel. Wait for each phase to complete before proceeding.

Context Window Protection: You are orchestrating commands, not sub-agents. Your context window is safe because you're invoking slash commands sequentially, not spawning multiple agents.

State Management: TodoWrite provides real-time progress visibility. Update it at every phase transition.

Fail Fast: When Tier 3 issues occur or user declines fixes, exit immediately with clear guidance. Don't attempt complex recovery.

Dependency Enforcement: Never skip dependency checks. Review phases are sequential, validation phases are tiered.

One-shot Fixes: Apply each fix once, re-run once, then fail if still broken. This prevents infinite loops.

User Communication: Report progress clearly. Show which phase is running, what the result was, and what's happening next.

Workflow Architecture

Two paths based on research availability: Path 1 (research exists) and Path 2 (research needed). TodoWrite tracks progress through 8-10 phases. Entry point detection uses prompt analysis and AskUserQuestion.

Details: See references/workflow-architecture.md

Workflow Execution

Sequential phase invocation pattern: mark in_progress → check dependencies → invoke command → check result → apply fixes → mark completed → continue. Dependencies enforced (review sequential, validation tiered). Commands invoked via SlashCommand tool with wait-for-completion pattern.

Details: See references/workflow-execution.md

Success Completion

When all phases pass successfully:

✅ Skill created and validated successfully!

Location: <skill-output-path>/

Research materials: docs/research/skills/<skill-name>/
Keep research materials? [Keep/Remove] (default: Keep)

Artifact Cleanup:

Ask user about research materials:

• Keep (default): Preserves research for future iterations, builds knowledge base
• Remove: Cleans up workspace, research can be re-gathered if needed

Next Steps:

Present options to user:

Next steps - choose an option:
  [1] Test in new session - Skills require session reload to be discoverable
  [2] Create PR - Submit skill to repository
  [3] Done - Exit workflow

What would you like to do?

User Actions:

1. Test in new session → Skills load at session start. User must restart Claude Code to test.
2. Create PR → Create git branch, commit, push, open PR
3. Done → Clean exit

Note: Skills auto-discover based on directory structure - no plugin.json registration needed.

Execute the user's choice, then exit cleanly.

Examples

The skill-factory workflow supports various scenarios:

1. Path 2 (Full Workflow): Creating skills from scratch with automated research gathering
2. Path 1 (Existing Research): Creating skills when research materials already exist
3. Guided Fix Workflow: Applying Tier 2 fixes with user approval
4. Fail-Fast Pattern: Handling Tier 3 complex issues with immediate exit

Detailed Examples: See references/workflow-examples.md for complete walkthrough scenarios showing TodoWrite state transitions, command invocations, error handling, and success paths.

Design Principles

Six core principles: (1) Primitives First (slash commands foundation), (2) KISS State Management (TodoWrite only), (3) Fail Fast (no complex recovery), (4) Context-Aware Entry (prompt analysis), (5) Composable & Testable (standalone or orchestrated), (6) Quality Gates (sequential dependencies).

Details: See references/design-principles.md

Implementation Notes

Command-Based Architecture

skill-factory orchestrates 9 primitive slash commands through a sequential workflow:

Creation Phase:

• /meta-claude:skill:research → Gather domain knowledge via firecrawl
• /meta-claude:skill:format → Clean and structure research materials
• /meta-claude:skill:create → Scaffold skill directory with references (runs init_skill.py)
• /meta-claude:skill:write → Synthesize references into SKILL.md content

Validation Phase:

• /meta-claude:skill:review-content → Quality gate for clarity and completeness
• /meta-claude:skill:review-compliance → Technical validation via quick_validate.py
• /meta-claude:skill:validate-runtime → Test actual skill loading
• /meta-claude:skill:validate-integration → Check for naming conflicts
• /meta-claude:skill:validate-audit → Comprehensive audit via claude-skill-auditor agent

Each command is standalone and testable. skill-factory provides orchestration, not abstraction.

Progressive Disclosure

This skill provides:

1. Quick Start - Fast path for common use cases
2. Workflow Architecture - Understanding the orchestration model
3. Detailed Phase Documentation - Deep dive into each phase
4. Error Handling - Comprehensive fix strategies
5. Examples - Real-world scenarios

Load sections as needed for your use case.

Troubleshooting

Common issues: research phase failures (check FIRECRAWL_API_KEY), content review loops (Tier 3 issues need redesign), compliance validation (run quick_validate.py manually), integration conflicts (check duplicate names).

Details: See references/troubleshooting.md

Success Metrics

You know skill-factory succeeds when:

1. Time to create skill: Reduced from hours to minutes
2. Skill quality: 100% compliance with official specs on first validation
3. User satisfaction: Beginners create high-quality skills without deep knowledge
4. Maintainability: Primitives are independently testable and reusable
5. Workflow clarity: Users understand current phase and next steps at all times

Related Resources

• multi-agent-composition skill - Architectural patterns and composition rules
• Primitive commands - Individual slash commands under /meta-claude:skill:* namespace
• quick_validate.py - Compliance validation script
• skill-audit-agent - Comprehensive skill audit agent