skills-factory

Skills Factory

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

About Skills

Skills extend Claude Code's capabilities with specialized knowledge and workflows. They use a two-level progressive disclosure system:

1. Description (YAML description field) - Always loaded into context at startup. Claude uses this to decide when to invoke the skill.
2. Full Content (SKILL.md body + referenced files) - Loaded when the skill is invoked, either by Claude or the user.

Skills are filesystem-based and live in:

• ~/.claude/skills/ - Personal skills (available across all projects)
• .claude/skills/ - Project skills (version-controlled, shared via git)
• .claude/commands/ - Backward-compatible location (also works)

Priority resolution (when same name exists at multiple levels): Enterprise > Personal > Project.

Note: Skills follow the Agent Skills open standard for cross-platform compatibility.

Context budget: Skill descriptions consume context. Total budget is ~2% of context window (default ~16k chars). If you have many skills, keep descriptions concise or use disable-model-invocation: true on rarely-needed skills.

---

Workspace Convention

CRITICAL: All eval and benchmark operations use this predetermined directory layout. Scripts, agents, and viewers depend on these exact paths. Do NOT deviate.

<skill-workspace>/
├── SKILL.md                          # The skill under development
├── evals/
│   ├── evals.json                    # Test cases (see SCHEMAS.md > evals.json)
│   ├── trigger-eval.json             # Trigger queries (see SCHEMAS.md > trigger-eval.json)
│   └── files/                        # Input files referenced by evals
├── iteration-<N>/                    # One per eval cycle (iteration-0 = baseline)
│   ├── eval-<ID>/                    # One per eval case
│   │   ├── with_skill/               # Runs WITH the skill loaded
│   │   │   ├── run-<M>/
│   │   │   │   ├── outputs/          # Executor output files + metrics.json
│   │   │   │   ├── transcript.md     # Full executor transcript
│   │   │   │   ├── grading.json      # Grader output (SCHEMAS.md > grading.json)
│   │   │   │   └── timing.json       # Wall clock + token counts
│   │   │   └── ...
│   │   └── without_skill/            # Runs WITHOUT the skill (baseline)
│   │       └── run-<M>/
│   │           └── (same structure)
│   ├── benchmark.json                # Aggregated stats (SCHEMAS.md > benchmark.json)
│   └── benchmark.md                  # Human-readable summary
├── description-optimization/         # Trigger description tuning
│   ├── results.json                  # run_loop.py output
│   └── report.html                   # Visual optimization report
└── history.json                      # Iteration progression tracker