skillforge

name	skillforge
description	Intelligent skill router and creator. Analyzes ANY input to recommend existing skills, improve them, or create new ones. Uses deep iterative analysis with 11 thinking models, regression questioning, evolution lens, and multi-agent synthesis panel. Phase 0 triage ensures you never duplicate existing functionality. Use when you say "create a skill", "do I have a skill for", "which skill should I use", "improve the X skill", or "SkillForge: {goal}". Do NOT use to create a slash command (use slashcommandcreator).
license	MIT
user-invocable	true
allowed-tools	["Read","Glob","Grep","Write","Edit"]
metadata	{"version":"4.1.0","subagent_model":"claude-opus-4-6","domains":["meta-skill","automation","skill-creation","orchestration","agentic","routing"],"type":"orchestrator","inputs":["any-input","user-goal","domain-hints"],"outputs":["SKILL.md","references/","scripts/","SKILL_SPEC.md","recommendations"]}

SkillForge 4.1 - Intelligent Skill Router and Creator

Analyzes any input to find, improve, compose, or create the right skill.

---

Quick Start

SkillForge accepts direct creation requests, skill improvement requests, skill lookup questions, task prompts, error messages, URLs, and code snippets. It routes first, then creates only when no existing skill covers the need.

SkillForge: create a skill for automated code review
  -> Creates a new skill after checking for duplicates

help me debug this TypeError
  -> Recommends an existing debugging skill

improve the testgen skill to handle React components better
  -> Loads the skill and enters improvement mode

do I have a skill for database migrations?
  -> Recommends matching database skills

See references/overview-and-triggers.md for the full examples, triggers, routing diagram, and command summary. See references/phase0-triage.md for the full triage flow and script examples.

---

Triggers

Creation Triggers

• SkillForge: {goal}: full autonomous skill creation
• create skill: natural language activation
• design skill for {purpose}: purpose-first creation
• ultimate skill: maximum quality creation path
• SkillForge --plan-only: generate specification without execution

Routing Triggers

• {any input}: analyze and route automatically
• do I have a skill for: search existing skills
• which skill or what skill: recommend matching skills
• improve {skill-name} skill: improve an existing skill
• help me with or I need to: detect task and route

Input	Output	Quality Gate
Any input	Triage -> Route -> Action	Phase 0 analysis
Explicit create	New skill	Unanimous panel approval
Skill question	Skill recommendation	Match confidence >=60%

---

Process Overview

Any user input
  -> Phase 0: Skill triage
     -> USE_EXISTING, IMPROVE_EXISTING, CREATE_NEW, COMPOSE, or CLARIFY
  -> Phase 1: Deep analysis when creation or improvement is needed
  -> Phase 2: Specification with rationale and evolution score
  -> Phase 3: Generation of SKILL.md, references/, assets/, and scripts/
  -> Phase 4: Synthesis panel until unanimous approval
  -> Production-ready agentic skill

Key principles:

• Phase 0 prevents duplicate skills before any creation work starts.
• Evolution and timelessness scoring stays at the center. Score >=7 is required.
• Every decision includes WHY.
• Scripts are added when deterministic automation improves verification.
• Panel approval is unanimous before finalization.

Tool Escalation Policy

Start with least privilege: Read, Glob, Grep, Write, and Edit. Add Bash, WebFetch, WebSearch, or Task only when the current skill requires local scripts, external facts, or true parallel sub-agent orchestration.

---

Commands

Command	Action
SkillForge: {goal}	Full autonomous execution
SkillForge --plan-only {goal}	Generate specification only
SkillForge --quick {goal}	Reduced depth, not recommended
SkillForge --triage {input}	Run Phase 0 triage only
SkillForge --improve {skill}	Enter improvement mode for existing skill

---

Phase 0: Skill Triage

Classify the input, scan the skill ecosystem, score matches, then route to one of five actions. Recommend existing skills for strong matches (>=80%, or >=60% for skill questions), improve matches in the 50-79% range, create below 50%, compose multi-domain requests, and clarify only when ambiguity or duplicate risk blocks a safe route.

See references/phase0-triage.md for the decision matrix, script examples, ecosystem index, and integration with later phases.

---

Phase 1: Deep Analysis

Expand explicit requirements, implicit requirements, unknown unknowns, and domain context. Apply all 11 thinking models, run regression questioning until three rounds add no new insight, and identify automation opportunities.

See references/phase1-analysis-deep-dive.md, references/multi-lens-framework.md, and references/regression-questions.md.

---

Phase 2: Specification

Create the XML skill specification with metadata, context, requirements, architecture, scripts, evolution analysis, anti-patterns, and success criteria. Validate traceability, rationale, extension points, and timelessness before writing skill files.

See references/phase2-specification-deep-dive.md and references/specification-template.md.

---

Phase 3: Generation

Generate the skill directory in this order: structure, SKILL.md, references, assets, then scripts when scripts are needed. Keep SKILL.md concise and move deep detail into progressive-disclosure reference files.

See references/phase3-generation-deep-dive.md, references/output-structure.md, references/script-integration-framework.md, and references/script-patterns-catalog.md.

---

Phase 4: Synthesis Panel

Run 3-4 independent evaluators: design and architecture, audience and usability, evolution and timelessness, plus script and automation when scripts exist. All agents must approve. Rejections loop back into targeted analysis and generation.

See references/phase4-synthesis-deep-dive.md and references/synthesis-protocol.md.

---

Evolution and Architecture Selection

Evaluate each skill across 6-month, 1-year, 2-year, and 5-year horizons. Reject transient designs, revise tool-bound designs, and approve principle-based skills with extension points. Select the architecture pattern that fits task complexity.

See references/evolution-scoring.md, references/evolution-timelessness.md, and references/architecture-patterns.md.

---

Validation and Packaging

Before distribution, validate structure, frontmatter, scripts, documentation safety, and packaging. Keep command examples portable when a plugin-root path is needed.

# Validators enforce a path-traversal guard: the target skill directory must
# live under your current directory. Run them from an ancestor of the skill.
cd ~/.claude/skills
FORGE=~/.claude/skills/SkillForge/scripts   # adjust to your SkillForge install
python "$FORGE/quick_validate.py" my-skill/     # required before packaging
python "$FORGE/validate-skill.py" my-skill/     # full structural validation
python "$FORGE/package_skill.py" my-skill/ ./dist   # package for distribution

See references/output-structure.md for allowed frontmatter fields, directory layout, script categories, hook configuration, and output requirements.

---

Anti-Patterns

Avoid	Why	Instead
Duplicate skills	Bloats registry	Check existing first
Single trigger	Hard to discover	3-5 varied phrases
No verification	Cannot confirm success	Measurable outcomes
Over-engineering	Complexity without value	Start simple
Missing WHY	Cannot evolve	Document rationale
Invalid frontmatter	Cannot package	Use allowed properties only
Restating pre-trained knowledge	The model already knows SOLID, Clean Code, and the refactoring catalog. Restating it adds tokens and buys no behavior change.	Write only what the model cannot know: repo gotchas, local conventions, post-cutoff APIs
Body loaded when the description would do	The description is always visible; the body is not. If the body only elaborates the description, it is never the reason the skill worked.	Put the decision rule in the description, the depth in references/
Adding to always-on context	Passive context is billed on every request forever, whether or not the task needs it	Progressive disclosure by default; measure with scripts/validation/instruction_budget.py before proposing always-on text. The reasoning, the admission test, and the measured evidence are in context-optimizer/references/model-context-doctrine.md
Negative rule pileup	Long "never do X" lists cause overconstraint; the model optimizes for the prohibitions over the task	State the goal and the one costly failure to avoid; keep hard rules for genuinely expensive mistakes

---

Verification Checklist

After creation:

• Frontmatter valid with only allowed properties
• Name is hyphen-case and <=64 chars
• Description <=1024 chars, with no < or >
• 3-5 trigger phrases defined
• Timelessness score >=7
• python scripts/quick_validate.py passes
• python scripts/check_docs_safety.py passes
• No bare .claude/skills/... exec path in the generated SKILL.md; script invocations use the portable ${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/... form (see docs/SKILL-AUTHORING.md, "Portable Script Invocations")
• Reference links resolve
• Scripts self-verify when scripts are present
• Every claim in the body is something the model could not already know. Generic engineering knowledge moved to references/ or deleted
• Body earns its length: if the description alone would produce the same behavior, cut the body down to what it adds

---

Scripts

The scripts/ directory makes SkillForge agentic: it can scaffold, triage, validate, and package skills with self-verification. Scripts run on the Python 3 standard library; a few use PyYAML for frontmatter parsing when it is installed and fall back to a stdlib parser when it is not. Exit codes: 0 on success and non-zero on failure (1 general; individual scripts add 2 or 3 for specific precondition failures, documented in each script's --help).

Script	Purpose
triage_skill_request.py	Phase 0 triage: classify an input and route to build, improve, or reuse
discover_skills.py	Ecosystem scan: enumerate existing skills before creating a new one
init_skill.py	Scaffold a new skill directory from the standard structure
validate-skill.py	Full validation of a generated skill against SkillForge standards
quick_validate.py	Fast structural check of frontmatter and required sections
skill_modularity_audit.py	Audit SKILL.md size and flag progressive-disclosure violations
package_skill.py	Package a completed skill for distribution
check_docs_safety.py	Safety scan of generated documentation
frontmatter.py	Internal helper module: shared YAML frontmatter parsing (imported, not run directly)
_constants.py	Internal helper module: shared constants and thresholds (imported, not run directly)

See references/script-integration-framework.md for when to add scripts and references/script-patterns-catalog.md for the standard patterns.

---

References

Reference	Contents
Overview and Triggers	Original examples, trigger lists, routing diagram, commands
Phase 0 Triage	Input classification, ecosystem scan, decision matrix, triage scripts
Phase 1 Deep Dive	Input expansion, lens scan, regression questioning, automation analysis
Multi-Lens Framework	11 thinking models and application guidance
Regression Questions	Complete question bank and termination criteria
Phase 2 Deep Dive	Specification structure and validation
Specification Template	Full XML specification template
Phase 3 Deep Dive	Generation order and quality checks
Output Structure	Frontmatter, directory structure, scripts, hooks
Script Integration Framework	When and how to add scripts
Script Patterns Catalog	Standard Python script patterns
Phase 4 Deep Dive	Panel composition, script agent, evaluation format, consensus loop
Synthesis Protocol	Multi-agent panel execution details
Evolution Scoring	Timelessness scoring and evolution rubric
Evolution Timelessness	Temporal projection and anti-obsolescence patterns
Architecture Patterns	Pattern selection guide and decision tree
Configuration	SkillForge configuration defaults
Changelog

---

Related Skills

skill-composer (orchestrate created skills), claude-authoring-guide (deeper patterns), codereview (multi-agent panel pattern), maker-framework (zero-error standard).

Extension Points

Add thinking models, panel agents, architecture patterns, or script patterns via the matching references/*.md; add domain templates in assets/templates/.