skill-factory

What this skill does

# 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:

| Command | Purpose | Use When |
|---------|---------|----------|
| `/meta-claude:skill:research` | Gather domain knowledge using firecrawl API | Need automated web scraping for skill research |
| `/meta-claude:skill:format` | Clean and structure research materials | Have raw research needing markdown formatting |
| `/meta-claude:skill:create` | Initialize skill structure with references | Ready to scaffold skill directory from research |
| `/meta-claude:skill:write` | Synthesize references into SKILL.md content | Skill initialized but needs content written |
| `/meta-claude:skill:review-content` | Validate content quality and clarity | Need content review before compliance check |
| `/meta-claude:skill:review-compliance` | Run quick_validate.py on SKILL.md | Validate YAML frontmatter and naming conventions |
| `/meta-claude:skill:validate-runtime` | Test skill loading in Claude context | Verify skill loads without syntax errors |
| `/meta-claude:skill:validate-integration` | Check for conflicts with existing skills | Ensure no duplicate names or overlaps |
| `/meta-claude:skill:validate-audit` | Invoke claude-skill-auditor agent | Get comprehensive audit against Anthropic specs |

**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](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):**

| Scenario | Command | Why |
|----------|---------|-----|
| Need web research for skill topic | `/meta-claude:skill:research <name> [sources]` | Automated firecrawl scraping |
| Have messy research files | `/meta-claude:skill:format <research-dir>` | Clean markdown formatting |
| Ready to scaffold skill directory | `/meta-claude:skill:create <name> <research-dir>` | Creates structure with references |
| Skill initialized, needs content | `/meta-claude:skill:write <skill-path>` | Synthesizes references into SKILL.md |
| Content unclear or incomplete | `/meta-claude:skill:review-content <skill-path>` | Quality gate before compliance |
| Check frontmatter syntax | `/meta-claude:skill:review-compliance <skill-path>` | Runs quick_validate.py |
| Skill won't load in Claude | `/meta-claude:skill:validate-runtime <skill-path>` | Tests actual loading |
| Worried about name conflicts | `/meta-claude:skill:validate-integration <skill-path>` | Checks existing skills |
| Want Anthropic spec audit | `/meta-claude:skill:validate-audit <skill-path>` | Runs claude-skill-auditor |

**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:

```bash
# 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:

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

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

### Example Usage

```text
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:**

```text
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:

```text
"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):**

```javascript
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

Up