Skill Forge

Stop pasting strangers’ skills into your repo.

Every week someone on Reddit ships a “Top 10 Claude Code Skills You MUST Have” post. You copy them. They work — for the toy React project the author wrote them against. In your 4-year-old DDD monolith they recommend *Controller.cs when your team standardized on *Handler.cs three refactors ago, and now your junior is writing code that looks correct and reviews like a hostage situation.

Skill Forge is the opposite playbook. It refuses to import a single rule from the internet. Instead it reads your codebase, finds where your team actually disagrees with Microsoft Docs, and writes Claude skills that quote Features/Order/CreateOrderHandler.cs:42 as evidence — not Kent Beck.

Four skills in ten minutes. You type y or N for each. Nothing gets committed you didn’t approve. Works on Windows, macOS, Linux. Conforms to the official Claude Code Skills spec so Claude actually loads what we forge.

“Skills should be ergonomics for your team — not tourism brochures from someone else’s stack.”

---

Release Notes

[0.2.0] — 2026-05-17 — Spec-compliance pass. Four fixes against the official Claude Code Skills documentation:

Upgrading from 0.1.x? See the migration guide in CHANGELOG.md — 5 shell commands, no data loss.

Full history: CHANGELOG.md

---

---

Table of contents

1. What it does
2. Package layout
3. Prerequisites
4. Installation — choose one placement
5. Usage — Windows
6. Usage — macOS
7. Usage — Linux
8. Sample recon output
9. Setting the system prompt in Claude Code
10. The forge workflow (what to type)
11. Draft → Skill promotion flow
12. Re-forging when the codebase drifts
13. Troubleshooting

---

What it does

You run one script. It scans your repo (read-only) and writes 5 plain-text files to .claude/forge-recon/ describing the codebase. You then open Claude Code, load the Skill Forge system prompt, and pick a tier (1/2/3). Claude drafts skills that quote real path:Lxx from your repo, and you type y/N to promote each one. Strict review, no surprises.

Package layout

skill-forge/
├── QUICKSTART.md            # 3-step cheat sheet
├── README.md                # this file
├── prompts/SYSTEM.md        # Claude's system prompt
├── scripts/
│   ├── forge.sh             # Linux / macOS / Git Bash
│   └── forge.ps1            # Windows PowerShell (native)
└── templates/
    ├── SKILL.md             # frontmatter + body for each forged skill
    └── skill-forge-index.md # tracking manifest (lives OUTSIDE .claude/skills/)

Prerequisites

You also need Claude Code installed and authenticated. The script itself does not call Claude — it only prepares files Claude will read.

Installation — choose one placement

Option A — Vendor inside the project (recommended for teams)

Clone Skill Forge somewhere temporary, then copy its files into tools/skill-forge/ inside your project. This vendors the source — no submodule, no extra clone flags for teammates, no surprise breakage when the upstream moves.

# 1. Clone Skill Forge to a temporary location
git clone https://github.com/jarvis823/skill-forge.git /tmp/skill-forge

# 2. Copy into your project under tools/
cd /path/to/your/project
mkdir -p tools
cp -r /tmp/skill-forge tools/skill-forge

# 3. Drop the upstream .git so it doesn't conflict with your repo
rm -rf tools/skill-forge/.git

# 4. Commit it as part of your project
git add tools/skill-forge
git commit -m "chore: vendor skill-forge under tools/"

New joiners then only need the normal clone of your project — nothing special, no submodule flags to remember:

git clone https://your-git-host/your-project.git
cd your-project
# tools/skill-forge/ is already there as regular files

Windows (PowerShell) equivalent:

git clone https://github.com/jarvis823/skill-forge.git $env:TEMP\skill-forge
cd D:\path\to\your\project
New-Item -ItemType Directory -Force -Path tools | Out-Null
Copy-Item -Recurse $env:TEMP\skill-forge tools\skill-forge
Remove-Item -Recurse -Force tools\skill-forge\.git
git add tools/skill-forge
git commit -m "chore: vendor skill-forge under tools/"

Why vendor instead of submodule? Submodules are powerful but a notorious footgun for new joiners — forget --recurse-submodules once and you waste an afternoon. Vendoring is dumb, durable, and version-pinned by your own commit history. When you want to upgrade, repeat the steps above and review the diff.

Option B — Standalone clone outside the project (recommended for solo devs)

git clone https://github.com/jarvis823/skill-forge.git ~/skill-forge

Then point at the target project via the --repo / -Repo flag (see below).

---

Usage — Windows

One-time setup

PowerShell blocks unsigned scripts by default. Allow local scripts to run:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

RemoteSigned means: local scripts run freely, scripts downloaded from the internet require a signature. Safe for development.

Run recon

If skill-forge is inside the project (Option A):

cd D:\Working\Mobile\quick_saves
.\tools\skill-forge\scripts\forge.ps1

If skill-forge is outside the project (Option B):

C:\tools\skill-forge\scripts\forge.ps1 -Repo D:\Working\Mobile\quick_saves

Expected console output

Skill Forge recon @ a1b2c3d
Output: D:\Working\Mobile\quick_saves\.claude\forge-recon

[1/5] Tree...
[2/5] Languages...
[3/5] Manifests...
[4/5] Entry points...
[5/5] Tests...

Done. Recon files:

Name               Length LastWriteTime
----               ------ -------------
01-tree.txt           258 5/16/2026 5:20:40 PM
02-languages.txt       94 5/16/2026 5:20:40 PM
03-manifests.txt       49 5/16/2026 5:20:40 PM
04-entrypoints.txt     52 5/16/2026 5:20:40 PM
05-tests.txt          102 5/16/2026 5:20:40 PM

Next: open Claude Code, set system prompt = prompts/SYSTEM.md, then reply 1/2/3.

---

Usage — macOS

One-time setup

Make the script executable (only the first time after clone):

chmod +x ~/skill-forge/scripts/forge.sh
# Or if vendored inside the project:
chmod +x tools/skill-forge/scripts/forge.sh

Run recon

From inside the project (auto-detects git root):

cd ~/work/quick_saves
bash tools/skill-forge/scripts/forge.sh

Pointing at a target project from anywhere:

bash ~/skill-forge/scripts/forge.sh --repo ~/work/quick_saves

Expected console output

Skill Forge recon @ a1b2c3d
Output: /Users/jimmy/work/quick_saves/.claude/forge-recon

[1/5] Tree...
[2/5] Languages...
[3/5] Manifests...
[4/5] Entry points...
[5/5] Tests...

Done. Recon files:
total 40
-rw-r--r--  1 jimmy  staff   258 May 16 17:20 01-tree.txt
-rw-r--r--  1 jimmy  staff    94 May 16 17:20 02-languages.txt
-rw-r--r--  1 jimmy  staff    49 May 16 17:20 03-manifests.txt
-rw-r--r--  1 jimmy  staff    52 May 16 17:20 04-entrypoints.txt
-rw-r--r--  1 jimmy  staff   102 May 16 17:20 05-tests.txt

Next: open Claude Code, set system prompt = prompts/SYSTEM.md, then reply 1/2/3.

---

Usage — Linux

One-time setup

chmod +x tools/skill-forge/scripts/forge.sh
# Optional but improves the tree output:
sudo apt install tree     # Debian/Ubuntu
sudo dnf install tree     # Fedora

Run recon

From inside the project:

cd ~/work/quick_saves
bash tools/skill-forge/scripts/forge.sh

Pointing at a target project from anywhere:

bash ~/skill-forge/scripts/forge.sh --repo ~/work/quick_saves

Expected console output

Identical to macOS, just with linux paths.

---

Sample recon output

Below is what Claude will read on its first turn — make sure these files look sensible before continuing. If 02-languages.txt shows mostly .lock or .json files, your recon picked up vendored code; check exclude patterns.

01-tree.txt

# Top-level layout (depth 2)
[DIR]  .claude
[DIR]  .claude/forge-recon
[DIR]  .claude/skills
[DIR]  .claude/skills-draft
       go.mod
[DIR]  internal
[DIR]  internal/billing
       package.json
[DIR]  src
[DIR]  src/Features
[DIR]  tests
[DIR]  tests/Order

02-languages.txt

# File count by extension (top 20)
     3  cs
     2  go
     1  json
     1  mod
     1  txt

03-manifests.txt

# Build/dependency manifests
go.mod
package.json

04-entrypoints.txt

# Likely entry points
src/Features/Order/Program.cs

05-tests.txt

# Co-located test files (first 50)
internal/billing/refund_test.go

# Test directories/projects
tests

---

Setting the system prompt in Claude Code

Claude Code reads CLAUDE.md at the project root automatically. The easiest way to load the Skill Forge prompt is to import it from CLAUDE.md:

Windows (cmd or PowerShell)

cd D:\Working\Mobile\quick_saves
echo @tools/skill-forge/prompts/SYSTEM.md > CLAUDE.md

macOS / Linux

cd ~/work/quick_saves
echo "@tools/skill-forge/prompts/SYSTEM.md" > CLAUDE.md

Verify it loaded

Open Claude Code in the project, then ask:

What role are you playing right now?

Pass: Claude replies with something like “Skill Forge ready. Recon files in .claude/forge-recon/. Reply with 1, 2, 3, or custom.”

Fail: Claude replies generically “I’m Claude, an AI assistant”. The import didn’t load — check CLAUDE.md content and the path inside it.

⚠️ The filename must be exactly CLAUDE.md (all uppercase). Windows is case-insensitive so this works locally, but a teammate on Linux will hit a broken import if you accidentally save it as Claude.md.

---

The forge workflow (what to type)

After Claude greets you with the tier menu:

Step 1 — Pick a tier

Type just a number or custom:

Step 2 — Approve the proposal

Claude prints a one-screen plan: each skill with rationale and which evidence file backs it. You reply y to proceed, or N to abort and rethink.

Example:

Plan for Minimal tier:

1. code-reviewer       ← evidence: src/Features/Order/*.cs (HIGH)
2. test-author         ← evidence: internal/billing/refund_test.go (HIGH)
3. feature-scaffolder  ← evidence: src/Features/Order/ structure (MEDIUM)
4. drift-doctor        ← meta-skill, monitors others (HIGH)

Proceed to draft? [y/N]

Step 3 — Approve each draft one-by-one

For each skill, Claude writes a draft and asks y/N/edit:

Drafted: .claude/skills-draft/code-reviewer/SKILL.md
  Confidence: HIGH
  Evidence:
    - src/Features/Order/CreateOrderHandler.cs:14-32
    - src/Features/Order/CreateOrderRequest.cs:1-28
    - internal/billing/refund.go:38-62
  Drift findings: 2

Promote `code-reviewer` to .claude/skills/? [y/N/edit]

y → Claude moves the folder, updates .claude/skill-forge-index.md, moves on to the next skill. N → draft stays in .claude/skills-draft/; you can review later or delete. edit → Claude asks what to change, redrafts, asks again.

---

Draft → Skill promotion flow

This is the part the official spec is strict about. Each skill is a directory, not a flat file.

Before promotion (draft state)

.claude/
├── forge-recon/                        # recon files, read-only
│   ├── 01-tree.txt
│   └── ...
├── skills-draft/                       # all current drafts live here
│   ├── code-reviewer/
│   │   └── SKILL.md                    # ← draft, NOT loaded by Claude Code
│   ├── test-author/
│   │   ├── SKILL.md
│   │   └── examples/
│   │       └── sample-test.cs          # supporting file
│   └── feature-scaffolder/
│       └── SKILL.md
└── skills/                             # empty until you approve

You type y for test-author

Claude performs these exact steps:

1. Create .claude/skills/test-author/
2. Move .claude/skills-draft/test-author/SKILL.md → .claude/skills/test-author/SKILL.md
3. Move .claude/skills-draft/test-author/examples/ → .claude/skills/test-author/examples/
4. Remove the now-empty .claude/skills-draft/test-author/ directory
5. Append a row to .claude/skill-forge-index.md (kept OUTSIDE skills/ — see Spec compliance)

After promotion (committed state)

.claude/
├── skills-draft/                       # code-reviewer + feature-scaffolder still here
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── feature-scaffolder/
│       └── SKILL.md
└── skills/                             # ← only what you approved
    # NO flat files here — spec treats every child as a skill directory
    └── test-author/
        ├── SKILL.md                    # ← Claude Code now auto-loads this
        └── examples/
            └── sample-test.cs

What gets committed to Git

Add these to your repo:

git add .claude/skills/
git commit -m "feat: forge initial skill set (tier: minimal)"

Add these to .gitignore (they’re disposable):

.claude/forge-recon/
.claude/skills-draft/

The recon is reproducible (forge.sh / forge.ps1 regenerates it any time) and drafts are work-in-progress noise. Only the approved skills belong in Git.

---

Re-forging when the codebase drifts

After a major refactor, regenerate the recon and ask Claude to diff:

# Step 1 — fresh recon
bash tools/skill-forge/scripts/forge.sh          # or .ps1 on Windows

# Step 2 — in Claude Code, type:

Re-forge. Compare new recon against existing skills in .claude/skills/. Surface skills whose evidence files have changed and propose updates.

Claude will:

• Read the existing skills in .claude/skills//SKILL.md
• Re-check whether the cited path:Lxx anchors still match the current code
• For each drifted skill, write an updated draft to .claude/skills-draft//
• Ask y/N per skill before overwriting

Same strict-review gate. No silent overwrites.

---

Troubleshooting

“bash: not recognized” on Windows

You’re in cmd.exe. Either:

• Use the PowerShell version: .\tools\skill-forge\scripts\forge.ps1
• Or open Git Bash (right-click the project folder → “Git Bash Here”)

“cannot be loaded because running scripts is disabled” on PowerShell

Run once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Recon output shows node_modules or vendor files

The exclusion patterns missed your folder layout. Open forge.sh / forge.ps1, find the ExcludeDirs / exclusion list, and add your folder name. Re-run.

Claude greets generically instead of saying “Skill Forge ready”

The system prompt didn’t load. Check:

1. CLAUDE.md exists at project root
2. Its content is exactly: @tools/skill-forge/prompts/SYSTEM.md (or absolute path)
3. The referenced path actually exists — case sensitive on macOS/Linux

Claude promotes drafts without asking y

Hard violation of the prompt. Reset by:

1. Move accidentally-promoted skills back to .claude/skills-draft/
2. Re-import the system prompt (it includes the strict-review rule)
3. If it happens twice in one session, restart Claude Code

“Repository not detected” warning

You ran the script outside a git repo. The script still works (it scans the current directory) but repo_sha will be no-git in the skill metadata. Either run inside a git repo, or accept the limitation for sandbox/prototype work.

---

When NOT to use this package

• Repo < 2 weeks old — no real conventions to detect yet
• You want fully autonomous AI — wrong philosophy, use a different tool
• You need one universal skill pack across many repos — forge per repo instead

License

Licensed under the Apache License 2.0.

In plain English: you can use, modify, fork, redistribute, even use this commercially — just keep the copyright notice and the LICENSE / NOTICE files intact. If you contribute back, your contribution is also Apache 2.0.

Apache 2.0 was chosen over MIT specifically for the explicit patent grant and retaliation clause (§3) — protects both the author and downstream users from patent shakedowns. See the Release Notes commentary for the full rationale.

Third-party trademarks (Claude, Anthropic, Microsoft, Go, etc.) belong to their respective owners and are referenced descriptively only — see NOTICE.