skill-forge

skill-forge

中文版

A Claude Code plugin that turns skill creation, discovery, iteration, and optimization into a skill itself — a meta-system for skills.

Why

Claude Code skills solve "how to codify workflows into reusable slash commands." But three gaps remain:

Gap	skill-forge's Answer
Don't know when to create a skill	Auto-detects complex tasks, proactively asks
Don't know if a skill is well-written	Built-in 4-dimension evaluator, won't save below threshold
Don't know if a skill will actually trigger	Dedicated description optimization phase, eval-driven

Install

Via CLI (recommended):

npm install -g @nekocode/skill-forge
skill-forge install

Or manually in Claude Code (installs to user-global scope):

/plugin marketplace add nekocode/skill-forge
/plugin install skill-forge

Run skill-forge doctor to verify your environment.

Commands

Command	What it does
/scan [prompt]	Scan project for skill opportunities. Optional prompt as focus hint
/create <prompt>	Create a new skill from prompt. Name auto-derived
/improve <prompt>	Iterate existing skill from prompt. Target matched from registry
/rename <old> <new>	AI-driven skill rename — updates dir, SKILL.md body, workspace, registry

Auto mode: After complex tasks (5+ tool calls), the Stop hook detects the pattern and offers to create a skill — no manual invocation needed.

How It Works

Design Principles

1. Hermes Agent — Autonomous creation with concrete trigger conditions; patch over rewrite
2. planning-with-files — File system as persistent working memory (context window = RAM, files = disk)
3. Anthropic skill-creator — Eval-driven quality: description is a separate optimization problem, 20-case trigger evals, explain why not just what
4. DSPy — All internal prompts (evaluation, improvement guidance) are self-optimized: structured FP/FN failure analysis, directional improvement, eval-driven variant selection

Dual-File Security Model

External content (grep/glob/read output) goes to .skill-forge/insights.md (low trust, hooks don't read it). Only after validation does content get promoted to .skill-forge/draft.md (high trust, injected by hooks). This prevents prompt injection amplification. Workspace lives at project-local ./.skill-forge/ — outside .claude/ entirely, so write permissions don't need the trust-boundary exemption and Python/shell both resolve the same absolute path without any slug-translation step.

Staging + Finalize

New skills are assembled in .skill-forge/staging/<name>/ (SKILL.md, scripts/, CHANGELOG, .opt/). finalize_skill.py then runs shutil.copytree in a subprocess to move the tree into .claude/skills/<name>/ — bypassing Claude's tool permission layer, which would otherwise prompt on any Write into a not-yet-real skill dir (empty dirs fail the trust-boundary exemption until a SKILL.md lands). Improve mode uses the same staging path: init_improve.py copies the live skill into staging, Claude edits there, and finalize --mode update rmtree's the target and copies staging back atomically.

Hooks Architecture

Skill-scoped hooks (SKILL.md frontmatter) — only active when skill-forge is engaged. All four run via one Python entrypoint (hook_draft_inject.py / skill_check.py) for cross-platform consistency:

• UserPromptSubmit — Inject draft header into attention window
• PreToolUse — Small draft-head dump before Read/Glob/Grep/Bash (goal-drift guard)
• PostToolUse — Nudge draft update after Write/Edit
• Stop — Check for unprocessed skill opportunities (skipped when a draft is active, to prevent self-looping)

Global hooks (hooks/hooks.json, auto-registered by plugin system):

• SessionStart — Reset counters + inject skill inventory
• PostToolUse — Tool counting + registry update on SKILL.md writes
• Stop — Detect complex workflows, trigger auto mode
• PreCompact — Mark compact state to prevent false positives
• UserPromptSubmit — Keyword matching for skill creation prompts

Skill Lifecycle

Complex task completed
  -> Stop hook / manual invocation
  -> scan -> create (draft -> research -> SKILL.md -> eval >= 6/8)
  -> .claude/skills/<name>/SKILL.md
  -> improve (diagnose -> content patch / trigger eval loop -> changelog + version bump)
  -> repeat after real usage

Session Catchup

On each new session, skill_catchup.py scans the previous session's JSONL for uncaptured complex tasks (5+ tool calls after last draft write). Solves "forgot to save as skill yesterday."

Evaluation Criteria