name: skillforge description: "Use when creating, improving, finding, or auditing agent skills - the user says 'create a skill', 'do I have a skill for X', 'improve the X skill', 'which skill should I use', asks whether a skill exists for a task, or wants to validate, test, evaluate, package, or health-check skills. Also use for skill ecosystem maintenance (duplicate detection, stale skills, trigger collisions) and advisor checkpoints." license: MIT user-invocable: true allowed-tools:

• Read
• Glob
• Grep
• Bash
• Write
• Edit
• Task metadata: version: 6.0.0 domains: [meta-skill, skill-creation, skill-testing, orchestration, routing] type: orchestrator

SkillForge 6 - Skill Router, Creator & Ecosystem Maintainer

Routes any skill-related request to the right action (use, improve, create, compose), creates new skills through an evidence-driven pipeline, and maintains the health of the whole skill ecosystem. Core principle: skill quality is a property of behavior, not documents - a skill is done when a fresh agent demonstrably does better with it than without it.

Routing (Phase 0)

Always triage before creating anything:

python3 scripts/discover_skills.py            # refresh index (auto-refreshes if >24h old)
python3 scripts/triage_skill_request.py "<the user's request>" --json

Match bands are keyword-evidence heuristics, not calibrated probabilities - report them as "strong/moderate/weak match", never as percent confidence.

Creation pipeline

Run phases in order. Each phase's detailed procedure lives in its reference - read the reference when you reach the phase, not before.

0. Baseline gate (RED). Before designing anything, dispatch a fresh subagent (Task tool) on 1-2 representative target tasks WITHOUT the skill. Capture verbatim what it does wrong. If the baseline does not fail, stop - the skill is unnecessary. The failures become the skill's test cases and its description keywords. See references/testing-and-evals.md.

1. Analysis. Identify explicit, implicit, and discovered requirements. Apply the three load-bearing lenses - Inversion (what guarantees failure → anti-patterns), Pareto (which 20% of scope delivers 80% → cut the rest), Root Cause (is this the real problem?) - plus any others from references/multi-lens-framework.md that earn their tokens. Classify the failure type you are guarding against and match the guidance form to it (see the failure-form table in references/testing-and-evals.md). Choose instruction specificity with references/degrees-of-freedom.md. Decide scripts with references/script-integration-framework.md.

2. Specification. Write the spec using references/specification-template.md. Minimal tier (problem, requirements, decisions with WHY, success criteria, test scenarios) for most skills; full tier (temporal projection, obsolescence triggers, extension points) only for infrastructure skills. Never fill a section you cannot ground - omit it.

3. Generation in fresh context. Dispatch a subagent (Task tool) that receives ONLY the spec and the baseline failures - not the analysis transcript - to write SKILL.md and supporting files. Scaffold first: python3 scripts/init_skill.py <name> --path <skills-dir>. Description doctrine: trigger conditions only, third person, symptom keywords, never a workflow summary. Budget: SKILL.md under 1,500 words; move depth to references/; <details> tags save zero tokens for agents - do not use them.

4. Execution testing (GREEN). Re-run the baseline tasks WITH the skill via fresh subagents. Gate on behavioral delta: the with-skill runs must not exhibit the baseline failures. Then run the description-triggering check (positive and near-miss queries). Iterate description and body against observed failures, not hunches. For improvements to existing skills, use blind A/B judging. Full protocols: references/testing-and-evals.md.

5. Review = lint + one adversarial reviewer. Mechanical gates first:

python3 scripts/validate_skill.py <skill-dir>     # structure, frontmatter, lint (pinned models, word budget, description shape)
python3 scripts/check_docs_safety.py <skill-dir>

Then one fresh-context subagent prompted to REFUTE the skill (find the case where it misleads, over-triggers, or fails its own scenarios), carrying the reviewer checklists in references/synthesis-protocol.md. Fix what it proves; ship what survives. Do not convene approval panels - same-model unanimity measures nothing.

6. Ship with evals. Every generated skill keeps its tests: an evals/ directory (trigger queries + behavioral scenarios + assertions) so future edits can be regression-tested with python3 scripts/run_skill_evals.py <skill-dir>. Iterate post-ship with references/iteration-guide.md.

Frontmatter and platform facts

Write frontmatter against the current Claude Code field set (17 fields) documented in references/claude-code-frontmatter.md, which also covers hooks (hooks receive JSON on stdin, not env vars), context: fork/agent, $ARGUMENTS, and the agentskills.io portability limits (64-char name, 1024-char description) that validate_skill.py enforces. Never pin dated model IDs (claude-*-YYYYMMDD) - the validator rejects them.

Ecosystem maintenance

python3 scripts/skillforge_doctor.py              # trigger collisions, duplicates, stale refs, token budgets, description lint
python3 scripts/compile_skill.py <dir> --target claude|codex|agentskills
python3 scripts/package_skill.py <dir> ./dist     # .skill zip, honors .skillignore
python3 scripts/mine_skill_friction.py --consent  # opt-in: mine local transcripts for skill friction

Use doctor output to drive IMPROVE_EXISTING work; use friction reports as advisor evidence.

Context Skill Advisor

Proactive suggestions are delivered through Claude Code hooks (SessionStart surfaces the queue; UserPromptSubmit scores checkpoints inline) - no daemon. Configure with python3 scripts/install_skillforge.py (interactive; hooks and Personal Context scanning are opt-in, never default). Manage the queue: python3 scripts/context_advisor.py list|use|snooze|dismiss. Suggestions are evidence-backed and never auto-invoke a skill.

Script inventory

Script exit codes: 0 success, 1 failure, 2 usage/consent error, 10 validation failure, 11 verification/dependency failure.

Extension points: new lint checks in validate_skill.py; new doctor checks in skillforge_doctor.py; new compile targets in compile_skill.py; new lenses in references/multi-lens-framework.md.

Anti-patterns

Verification checklist

• Baseline failure captured before writing (RED)
• With-skill runs clear the baseline failures (GREEN)
• Trigger check passes on positive and near-miss queries
• validate_skill.py and check_docs_safety.py pass
• Adversarial reviewer's proven issues fixed
• evals/ shipped with the skill; run_skill_evals.py passes
• SKILL.md under 1,500 words (wc -w)

SkillForge v6

A skill creator that proves its skills work.

SkillForge routes any skill-related request (use, improve, create, compose), creates new skills through an evidence-driven pipeline, and maintains the health of your whole skill ecosystem. Its core principle: skill quality is a property of behavior, not documents - a skill is done when a fresh agent demonstrably does better with it than without it.

What v6 changed (and why)

v6 is a ground-up rework following a deep external audit (see SKILLFORGE_AUDIT.md on the repo, not shipped with the skill). The headline shifts:

The pipeline

Phase 0  TRIAGE      index + word-boundary matching -> USE | IMPROVE | CREATE | COMPOSE | CLARIFY
Phase 0b RED GATE    fresh subagent attempts the task WITHOUT the skill; no failure = no skill
Phase 1  ANALYSIS    load-bearing lenses (Inversion, Pareto, Root Cause), failure-form matching
Phase 2  SPEC        tiered (minimal default / full for infrastructure), decisions + WHY
Phase 3  GENERATE    fresh-context subagent receives ONLY the spec + baseline failures
Phase 4  GREEN GATE  with-skill runs must clear the recorded baseline failures; trigger tests
Phase 5  REVIEW      lint (validate_skill.py) + ONE adversarial reviewer charged to refute
Phase 6  SHIP        with evals/ - a per-skill regression suite runnable forever after

What no other skill creator has

• Dedup before create (Phase 0): an index of every skill across runtimes answers "should this exist?" first.
• Skills ship with their tests: evals/ (trigger queries + behavioral scenarios) + run_skill_evals.py = regression testing for skills.
• Ecosystem doctor: skillforge_doctor.py finds trigger collisions between skills, duplicates, stale file references, budget violations, and pinned models across your entire roster.
• Cross-runtime compile: author once, compile_skill.py --target claude|codex|agentskills.
• Friction mining (opt-in): mine_skill_friction.py --consent finds skill gaps in your own local session history.
• Proactive advisor (opt-in): evidence-backed skill suggestions delivered via hooks, never auto-invoked.

Install (Claude Code)

git clone https://github.com/tripleyak/SkillForge.git /tmp/skillforge
cp -r /tmp/skillforge ~/.claude/skills/skillforge
cd ~/.claude/skills/skillforge && rm -rf README.md LICENSE CONTEXT.md docs .git .gitignore .skillignore index.html assets/images scripts/tests SKILLFORGE_AUDIT.md
cp /tmp/skillforge/commands/skillforge.md ~/.claude/commands/skillforge.md   # optional /skillforge command

Optional advisor + hooks (interactive, everything opt-in):

python3 ~/.claude/skills/skillforge/scripts/install_skillforge.py

Requirements: Claude Code (or Codex CLI), Python 3.8+ (stdlib only; PyYAML used if present).

Toolbox

CI: copy assets/templates/github-workflow-skill-ci.yml into .github/workflows/ of any skill repo.

Releases

Version history and detailed release notes live on the releases page. v6.0.0 is a ground-up rework; the audit that drove it ships in-repo as SKILLFORGE_AUDIT.md.

License

MIT - see LICENSE