skills-factory

Skills Factory

A comprehensive meta-skill for creating, validating, and iterating on production-ready Claude Code skills.

About Skills

Skills extend Claude Code's capabilities with specialized knowledge and workflows. They use a progressive disclosure system that loads content in three levels:

1. Metadata (YAML) - Always loaded at startup (~100 tokens)
2. Instructions (SKILL.md body) - Loaded when triggered (<5,000 tokens)
3. Resources (supporting files) - Loaded as needed (effectively unlimited)

Skills are filesystem-based tools that live in ~/.claude/skills/ (personal) or .claude/skills/ (project-specific).

Skill Creation Process

Step 1: Understanding the Domain

Before writing anything, deeply understand what you're building:

Ask Critical Questions:

• What specific problem does this skill solve?
• Who is the user and what's their context?
• What tasks should be automated vs. guided?
• What knowledge must Claude have vs. can reference?
• How will success be measured?

Research Thoroughly:

• Review similar existing skills
• Study relevant documentation
• Understand the workflow domain
• Identify edge cases and failure modes

Define Success Criteria:

• What specific outcomes indicate the skill works?
• What would success look like without the skill vs. with it?
• How will you evaluate effectiveness?

See: [references/EVALUATION_GUIDE.md](references/EVALUATION_GUIDE.md) for evaluation-driven development methodology.

Step 2: Planning Your Architecture

Design your skill's structure before implementation:

Choose Your Pattern:

• Simple skill: SKILL.md only (~100-300 lines)
• Standard skill: SKILL.md + 1-3 reference files
• Script-heavy skill: SKILL.md + scripts/ + validation patterns
• Reference-heavy skill: SKILL.md + references/ with 5+ supporting docs

Plan Progressive Disclosure:

• What must be in SKILL.md? (triggers, core workflow, navigation)
• What goes to references/? (detailed guides, examples, context)
• What goes to scripts/? (validation, automation, processing)
• Keep SKILL.md under 200 lines when possible

Design Workflows:

• Linear process? Use simple sequential steps
• Quality gates? Use checklist workflow
• Conditional paths? Design decision tree
• Iteration needed? Plan feedback loop

See: [references/WORKFLOW_PATTERNS.md](references/WORKFLOW_PATTERNS.md) and [references/VALIDATION_PATTERNS.md](references/VALIDATION_PATTERNS.md)

Step 3: Initialize Skill Structure

Create your skill's foundation:

cd ~/.claude/skills  # or .claude/skills for project-specific
python /path/to/init_skill.py my-skill-name

This creates:

my-skill-name/
├── SKILL.md          # Main skill file (YAML + instructions)
├── scripts/          # Executable scripts (optional)
├── references/       # Supporting documentation (optional)
└── assets/           # Images, templates, data files (optional)

Post-Initialization:

• Replace ALL TODO: placeholders in YAML frontmatter
• Draft description with key trigger terms (max 1024 chars)
• Ensure name is hyphen-case (lowercase + hyphens only)
• Plan your progressive disclosure structure

See: Bundled scripts/init_skill.py

Step 4: Design & Implement

Build your skill following best practices:

YAML Frontmatter Requirements:

---
name: skill-name          # Required: hyphen-case, max 64 chars
description: |            # Required: max 1024 chars, include trigger terms
  Clear, specific description of what this skill does.
  Include key terms that should trigger the skill.
  Focus on capabilities and use cases.
allowed-tools:            # Optional: Pre-approved tools list (Claude Code only)
  - Read
  - Grep
  - Glob
metadata:                 # Optional: Custom key-value pairs for tracking
  author: "TeamName"
  version: "1.0.0"
  category: "data-processing"
---

Optional YAML Fields:

allowed-tools (Claude Code only):

• Purpose: Restricts which tools Claude can use when this skill is active
• Format: YAML list of tool names
• Use Cases:
• Read-only skills (prevent file modification): [Read, Grep, Glob]
• Security-sensitive workflows (limit tool scope)
• Data analysis only (no write/execute permissions)
• Known Tools: Read, Write, Edit, Grep, Glob, Bash, Task, SlashCommand, Skill
• Example:

```yaml

name: safe-file-reader description: Read and analyze files without making changes allowed-tools: [Read, Grep, Glob]

```

metadata (All platforms):

• Purpose: Store custom key-value pairs for tracking and categorization
• Format: YAML dictionary (string keys → string values)
• Use Cases:
• Version tracking: {version: "2.1.0"}
• Team ownership: {author: "TeamName", contact: "team@example.com"}
• Categorization: {category: "content-creation", domain: "marketing"}
• Custom tracking IDs: {internal-id: "SKILL-12345"}
• Best Practice: Use unique key names to avoid conflicts with other tools
• Example:

```yaml

name: pdf-processor description: Extract text and tables from PDF files metadata: author: "ContentTeam" version: "2.1.0" category: "document-processing" last-updated: "2025-11-22"

```

SKILL.md Body Guidelines:

• Start with clear "About" section explaining purpose
• Use concrete examples over abstract explanations
• Break complex workflows into numbered steps
• Reference detailed content (don't inline everything)
• Keep total SKILL.md under 500 lines (ideally under 200)

Progressive Disclosure Rules:

• Reference files ONE level deep: [Guide](references/guide.md) ✓
• No nested references: references/category/subcategory/file.md ✗
• Load scripts when needed: "Run validation: bash scripts/validate.py"
• Front-load critical info, defer details to references

Workflow Integration:

• Add validation checkpoints after key steps
• Design feedback loops for quality assurance
• Use scripts to automate validation (not punt to Claude)
• Provide clear error messages with actionable fixes

See: [references/WORKFLOW_PATTERNS.md](references/WORKFLOW_PATTERNS.md), [references/VALIDATION_PATTERNS.md](references/VALIDATION_PATTERNS.md)

Step 5: Validate & Package

Ensure quality before distribution:

Comprehensive Validation:

python scripts/comprehensive_validate.py /path/to/my-skill-name

This checks:

• ✓ YAML structure and required fields
• ✓ Naming conventions (hyphen-case, no invalid chars)
• ✓ Description quality (length, clarity, trigger terms)
• ✓ Progressive disclosure (file references one-level deep)
• ✓ Best practices (no absolute paths, TODO markers, etc.)
• ✓ Content quality (examples present, clear structure)
• ✓ Workflow validation (if workflows present)

Fix all errors and warnings before packaging.

Package for Distribution:

python scripts/package_skill.py /path/to/my-skill-name

Creates: my-skill-name.zip ready for sharing or installation.

See: Bundled scripts/comprehensive_validate.py and scripts/package_skill.py

Step 6: Iterate Using Two-Claude Methodology

Most skills require iteration to reach production quality. Use the Two-Claude Method:

Claude A (Builder):

• Has the skill loaded in their environment
• Performs realistic tasks the skill should help with
• Documents behavior, errors, confusion points
• Takes notes on what works and what doesn't

Claude B (Tester/Observer):

• Reviews Claude A's session logs and outputs
• Analyzes where the skill succeeded vs. failed
• Identifies improvement opportunities
• Proposes specific edits to skill files

Iteration Cycle:

1. Claude A uses the skill on realistic task
2. Observe and document behavior (what happened?)
3. Claude B analyzes session (what should change?)
4. Edit skill files based on findings
5. Re-validate with comprehensive_validate.py
6. Repeat until skill performs well consistently

**Key Observation Po