skill-forge

When to invoke

~/.claude/skills/<name>/SKILL.md

mphinance/alpha-skills

~/.claude/projects/**/*.jsonl

reports/latest.md

Flow

forge mode

1. Ask the user 2-3 questions max: skill name (kebab-case), one-sentence purpose, primary trigger phrase. Don't over-interview.
2. Run the scaffolder.

   python scripts/forge_new.py --name <name> --brief "<one-sentence purpose>"

   The scaffolder reads

   templates/SKILL.md.tmpl

   and substitutes

   {{name}}

   ,

   {{description}}

   ,

   {{title}}

   ,

   {{when_to_invoke}}

   ,

   {{flow}}

   ,

   {{hard_rules}}

   .
3. Open the freshly written

   ~/.claude/skills/<name>/SKILL.md

   . Review with the user. Tighten copy if needed.
4. Publish.

   python scripts/publish.py <name>

   This clones

   mphinance/alpha-skills

   into

   ~/.cache/skill-forge/alpha-skills

   if missing, branches

   skill-forge/<name>-<short-ts>

   , commits, pushes, opens PR. Prints PR URL. Stop there. User reviews and merges.

audit mode

1. Run the miner.

   python scripts/mine_chats.py --days 30

2. Read

   reports/latest.md

   aloud (the markdown report) and

   reports/latest.json

   (structured candidates).
3. Present the three sections: new-skill candidates, refinement candidates, pain points. Ask which to act on.
4. For each chosen new-skill candidate, drop into forge mode with

   publish.py --from-audit

   so the PR body cites the mined evidence.
5. For each chosen refinement candidate, drop into refine mode.

refine mode

1. Read the target skill's existing SKILL.md in full. You are not allowed to remove or restructure anything.
2. Propose additions only: new trigger phrase in the frontmatter description, new example, new "When NOT to use" bullet, new flow step.
3. Write the proposed change to

   proposals/<skill-name>/CHANGES.diff

   first. Confirm with the user.
4. Apply the additive edit to

   ~/.claude/skills/<skill-name>/SKILL.md

   .
5. Publish.

   python scripts/publish.py <skill-name>

   Commit message starts with "Refine <name> skill: <one-line summary>". PR body explains the addition and links the mined evidence.

Hard rules

• Never auto-merge PRs.

  publish.py

  opens the PR. User merges. No

  gh pr merge

  ever.
• Never restructure existing skills in refine mode. Additive-only. If a skill needs a rewrite, that's a new forge, not a refine.
• Refinements are additive-only. No removed lines beyond pure whitespace.

  publish.py

  enforces this in refine mode.
• Never mine recursively on skill-forge's own sessions. The miner already filters self-references. Don't disable it.
• Skip SSH transcripts. Project paths starting with

  ssh-

  or cwd under

  /home/

  are remote work and not mined.
• No em dashes. Use en dash with spaces or commas. No emojis in forged skills.
• stdlib only. Forged skills and skill-forge scripts use Python stdlib, no pip installs.
• Always go through PR. Never edit files in

  ~/.cache/skill-forge/alpha-skills/skills/

  directly.

Scheduling

• Preferred – use the

  /schedule

  skill.

  /schedule weekly /skill-forge audit

  Runs the audit weekly, writes

  reports/latest.md

  , notifies you next session.
• Free-tier alternative for the miner alone. Wire Windows Task Scheduler to run

  python C:\Users\mphan\.claude\skills\skill-forge\scripts\mine_chats.py --days 7

  on a weekly trigger. Zero tokens spent. You read

  reports/latest.md

  when you feel like it, then invoke

  skill-forge audit

  interactively to act on candidates.

Out of scope

• Auto-merging PRs. User merges, always.
• In-place edits to skills in

  ~/.claude/skills/

  during refine mode. Always go through PR against

  mphinance/alpha-skills

  .
• Mining transcripts from machines other than this one.
• Forging non-markdown skills (binary plugins, MCP servers, anything that isn't a SKILL.md plus optional scripts).
• Rewriting or restructuring existing skills. Refinements are additive-only.