self-forge

self-forge — turn how you work into reusable Claude Code artifacts

You keep doing the same things by hand: re-typing the same prompt, re-explaining the same correction, walking the same five-step deploy, kicking off the same investigation. Each of those is a latent artifact. self-forge mines the evidence of what you actually do, ranks what's worth capturing, and forges it into the correct shape — a skill, a subagent, a hook, a slash command, a workflow, or a whole publishable plugin.

This skill is the analyst and the smith. It does not guess from a blank page; it reads your real usage and proposes from evidence.

Routing

Command	Action
/self-forge	Mine usage → rank → present a proposal report (no files written)
/self-forge:scaffold <id|description>	Build one approved proposal into a real artifact
/self-forge:publish [plugin]	Bundle artifacts into a plugin, publish to marketplace + docs

Invoked as a plain skill (no command), default to the propose behaviour: mine, rank, and present. Only write files after the user approves a specific proposal.

The core idea: signal → artifact

Every artifact type exists to capture a different kind of repetition. Match the signal to the shape — getting this mapping right is the whole game.

self-forge forges these six shapes:

You observe (the signal)	Forge this	Why this shape
Same prompt / phrasing typed repeatedly	slash command	A parameterized prompt template, one keystroke away
Repeated correction — "no, always…", "stop doing…", "from now on…"	hook	Deterministic enforcement the model can't forget
Multi-step procedure with domain knowledge (deploy, release, setup)	skill	Procedural knowledge + references, model-invoked on topic
Self-contained, delegable investigation / refactor, good in fresh context	subagent	Isolated context window, parallelizable, returns a conclusion
Multi-stage fan-out (find → verify → synthesize, audits, migrations)	workflow	Deterministic orchestration over many items/agents
A cluster of the above around one domain	plugin	Bundle + share + publish to the marketplace

self-forge routes these out — it spots the signal, then hands to the specialist that owns it (it does not reinvent them):

You observe (the signal)	Route to	What owns it
Repeatedly shelling the same CLI/API by hand	mcp-forge	A typed, guarded MCP tool surface
A durable fact / standard you keep restating	matts-second-brain	Cross-session knowledge (brain_remember)
Repeated permission prompts for one safe command	fewer-permission-prompts	settings.json allowlist (built-in)
Wanting stack/codebase-based suggestions, not usage-based	claude-automation-recommender	Codebase analysis (official)

The key boundary: self-forge forges from your observed behaviour — what you actually repeat and correct. The official claude-automation-recommender recommends from your codebase's shape (its frameworks and test runner) and stops at recommendations; self-forge ranks, scaffolds, and publishes. They complement; they do not duplicate.

The full decision logic, including tie-breakers and anti-patterns, is in references/signal-taxonomy.md — read it before classifying anything.

The pipeline

  MINE -> CLUSTER -> CLASSIFY -> SCORE -> PROPOSE -> (approve) -> SCAFFOLD -> (opt) PUBLISH
   |        |          |          |         |                       |
 evidence  group    pick the   rank by   ranked                 write files
 from      repeats  artifact   value vs  report                 in exact
 .claude   +friction  type     buildcost                        format

1. Mine. Run the deterministic miner — do not eyeball giant transcripts by hand:

   # resolves whether self-forge is installed as a plugin or as a loose global skill:
   SELF_FORGE_SKILL="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills/self-forge"
   python3 "$SELF_FORGE_SKILL/scripts/mine.py" --since-days 30 --transcripts --json
   

   Always pass --transcripts for a real run — without it you get prompt signals only and no tool-call or bash-command signals at all (so the MCP / workflow / session-hook branches go silent with no warning). If you spawn the usage-miner subagent, pass it the resolved absolute $SELF_FORGE_SKILL path — it starts with a fresh context and will not have this variable. If the window is thin (the miner flags thin, or nothing clears the floor), re-run with --since-days 90 before concluding.

   The miner returns structured counts of repeated prompts, tool-call sequences, correction phrases, and an inventory of what already exists (including skills shipped by installed plugins). It reads only local files and prints aggregates plus short, secret-redacted snippets of your own prompts — never assistant output or raw transcript bodies. See references/mining-playbook.md for exactly what it reads and how to read more by hand when a signal needs context.

2. Cluster. Group near-identical prompts/procedures into candidates. Three occurrences is the floor for proposing; note the count as evidence.

3. Classify. Map each candidate to one artifact type via references/signal-taxonomy.md. One candidate may legitimately suggest two (e.g. a skill and a hook); say so.

4. Score. Rank with the model in references/scoring-model.md: priority = (frequency × friction × automatability) / build_cost, gated by confidence. Drop anything below the proposal floor. Dedupe against the existing inventory — the miner lists your skills/commands/agents/hooks and the skills shipped by installed plugins (including official ones like claude-automation-recommender and skill-creator). Never propose what already exists; for any candidate whose intent overlaps an inventory entry, open that entry's file and dedupe by intent, not just by name. If it exists but is weak, propose improving it instead.

5. Propose. Present the ranked report (format below). Stop here. Do not write files yet.

6. Scaffold. On approval, forge the artifact in the exact format from references/artifact-formats.md, starting from templates/. Validate before declaring done.

7. Publish (optional). Bundle into a plugin and publish — see references/publishing.md.

The proposal report

Present findings as a ranked table, highest priority first, then one detail block per proposal:

## self-forge — N proposals from <window> of usage

| # | Forge | Name | Evidence | Priority | Confidence |
|---|-------|------|----------|----------|------------|
| 1 | hook    | block-rm-rf-prod      | 7× corrected   | High   | 0.9 |
| 2 | command | /review-security      | 12× typed      | High   | 0.85 |
| 3 | skill   | deploy-nutrition-saas | 5× walked      | Medium | 0.7 |
...

### 1. hook · block-rm-rf-prod
- Evidence: 7 corrections across 4 sessions ("never run rm against the prod volume").
- Shape: PreToolUse(Bash) deny-guard; regex on destructive paths.
- Build cost: ~20 lines Python. Hand-off: behavior-hooks if installed.
- Scaffold with: /self-forge:scaffold 1

Keep evidence concrete and quantified. Never invent counts — cite what the miner found.

Operating principles

• Evidence over imagination. Propose only what the usage data supports. "I found 6 occurrences" beats "you might want". If the miner is dry, do not pad the list — report its diagnostics (prompts, transcripts, and days it actually saw), show the existing inventory, name the single strongest weak signal if there is one, and say when to retry (--since-days 90, or after more usage). A credible "I looked, here is what I saw, come back when X" beats an invented proposal. Always return something concrete, even on a thin window.
• Right shape, not biggest shape. A repeated prompt is a command, not a plugin. Prefer the smallest artifact that captures the pattern. Escalate to a plugin only when several artifacts cluster around one domain.
• Dedupe ruthlessly. Always inventory existing skills/commands/agents/hooks/plugins first (references/mining-playbook.md). Improving an existing artifact usually beats adding a new one.
• Hand off, don't reinvent. Corrections → behavior-hooks. CLI wrapping → mcp-forge. Durable facts → matts-second-brain. Permission noise → fewer-permission-prompts. Settings → update-config. Codebase/stack-based recommendations → claude-automation-recommender (official). self-forge owns the one thing those do not: forging from your observed behaviour — what you actually repeat and correct — not from a codebase scan. It is the analyst that routes to the right specialist.
• Local and private. All analysis is on-disk. Never send transcript contents to any network tool. The miner emits aggregates; if you must quote a prompt, quote the user's own words briefly.
• Validate what you forge. A scaffolded artifact that doesn't load is worse than none. Lint frontmatter, JSON, and hook exit codes per references/artifact-formats.md before finishing.

What this skill ships

• scripts/mine.py — dependency-free local miner (stdlib only).
• references/signal-taxonomy.md — signal→artifact decision logic, with anti-patterns.
• references/mining-playbook.md — every file the miner reads + how to read more by hand.
• references/artifact-formats.md — exact authoring spec for each artifact type.
• references/scoring-model.md — ranking and the proposal floor.
• references/publishing.md — marketplace + docs publishing flow.
• templates/ — starting points for each artifact type.
• examples/ — a worked end-to-end run.

Load references on demand — do not read them all upfront. Read signal-taxonomy.md and mining-playbook.md for a /self-forge analysis run; read artifact-formats.md only when scaffolding; read publishing.md only when publishing.

Subagents

For a thorough run, fan the work out (see agents/):

• usage-miner — runs the miner and reads transcripts where a signal needs context; returns the structured signal report.
• artifact-architect — takes one signal and returns a concrete artifact design.
• artifact-smith — takes a design and writes the files in exact format.

A fast run can do all three inline. Use subagents when mining a large history or scaffolding several artifacts at once.