skill-forge

Name: skill-forge
Author: mphinance

46installs3forks

How to install skill-forge?

mphinance/alpha-skills/skill-forge

$npx -y skills add mphinance/alpha-skills --skill skill-forge

Installs into the current project.

Summary

Meta-skill that forges, audits, and refines other skills. Three modes – forge a new skill from a brief, audit recent chat transcripts for new-skill candidates and pain points, or refine an existing skill with additive-only changes. Triggers on "skill-forge a thing that does X", "

Files · 1

View on GitHub

SKILL.md

1	# skill-forge
2
3	The skill of skills, for skills. Builds new ones, refines existing ones, and mines chat transcripts for what to build next.
4
5	## When to invoke
6
7	Three modes. Pick by what the user says.
8
9	\| Mode \| Triggers \| What it does \|
10	\|---\|---\|---\|
11	\| forge \| "skill-forge a thing that does X", "forge a skill that ...", "build me a skill for ..." \| Ask 2-3 clarifying questions, scaffold `~/.claude/skills/<name>/SKILL.md` from the template, open PR to `mphinance/alpha-skills`. \|
12	\| audit \| "skill-forge audit", "skill audit", "/skill-forge", "what skills should I build" \| Run the miner over `~/.claude/projects/*/.jsonl`, present `reports/latest.md`, ask which candidates to forge or refine. \|
13	\| refine \| "refine my skills", "skill-forge refine <name>", "improve the <name> skill" \| Propose additive-only changes (new trigger phrase, new example, new section) to an existing skill. Opens PR with diff. \|
14
15	## Flow
16
17	### forge mode
18
19	1. Ask the user 2-3 questions max: skill name (kebab-case), one-sentence purpose, primary trigger phrase. Don't over-interview.
20	2. Run the scaffolder.
21	```
22	python scripts/forge_new.py --name <name> --brief "<one-sentence purpose>"
23	```
24	The scaffolder reads `templates/SKILL.md.tmpl` and substitutes `{{name}}`, `{{description}}`, `{{title}}`, `{{when_to_invoke}}`, `{{flow}}`, `{{hard_rules}}`.
25	3. Open the freshly written `~/.claude/skills/<name>/SKILL.md`. Review with the user. Tighten copy if needed.
26	4. Publish.
27	```
28	python scripts/publish.py <name>
29	```
30	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.
31
32	### audit mode
33
34	1. Run the miner.
35	```
36	python scripts/mine_chats.py --days 30
37	```
38	2. Read `reports/latest.md` aloud (the markdown report) and `reports/latest.json` (structured candidates).
39	3. Present the three sections: new-skill candidates, refinement candidates, pain points. Ask which to act on.
40	4. For each chosen new-skill candidate, drop into forge mode with `publish.py --from-audit` so the PR body cites the mined evidence.
41	5. For each chosen refinement candidate, drop into refine mode.
42
43	### refine mode
44
45	1. Read the target skill's existing SKILL.md in full. You are not allowed to remove or restructure anything.
46	2. Propose additions only: new trigger phrase in the frontmatter description, new example, new "When NOT to use" bullet, new flow step.
47	3. Write the proposed change to `proposals/<skill-name>/CHANGES.diff` first. Confirm with the user.
48	4. Apply the additive edit to `~/.claude/skills/<skill-name>/SKILL.md`.
49	5. Publish.
50	```
51	python scripts/publish.py <skill-name>
52	```
53	Commit message starts with "Refine <name> skill: <one-line summary>". PR body explains the addition and links the mined evidence.
54
55	## Hard rules
56
57	- Never auto-merge PRs. `publish.py` opens the PR. User merges. No `gh pr merge` ever.
58	- Never restructure existing skills in refine mode. Additive-only. If a skill needs a rewrite, that's a new forge, not a refine.
59	- Refinements are additive-only. No removed lines beyond pure whitespace. `publish.py` enforces this in refine mode.
60	- Never mine recursively on skill-forge's own sessions. The miner already filters self-references. Don't disable it.
61	- Skip SSH transcripts. Project paths starting with `ssh-` or cwd under `/home/` are remote work and not mined.
62	- No em dashes. Use en dash with spaces or commas. No emojis in forged skills.
63	- stdlib only. Forged skills and skill-forge scripts use Python stdlib, no pip installs.
64	- Always go through PR. Never edit files in `~/.cache/skill-forge/alpha-skills/skills/` directly.
65
66	## Scheduling
67
68	The audit is the part you want on a cron. Two options:
69
70	- Preferred – use the `/schedule` skill.
71	```
72	/schedule weekly /skill-forge audit
73	```
74	Runs the audit weekly, writes `reports/latest.md`, notifies you next session.
75
76	- 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.
77
78	Forge and refine modes are interactive by design. Don't schedule those.
79
80	## Out of scope
81
82	- Auto-merging PRs. User merges, always.
83	- In-place edits to

People who liked this also viewed

6 picks

Type

skill-forge

46installs3forks

View on GitHub

How to install skill-forge?

mphinance/alpha-skills/skill-forge

$npx -y skills add mphinance/alpha-skills --skill skill-forge

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# skill-forge
2
3	The skill of skills, for skills. Builds new ones, refines existing ones, and mines chat transcripts for what to build next.
4
5	## When to invoke
6
7	Three modes. Pick by what the user says.
8
9	\| Mode \| Triggers \| What it does \|
10	\|---\|---\|---\|
11	\| forge \| "skill-forge a thing that does X", "forge a skill that ...", "build me a skill for ..." \| Ask 2-3 clarifying questions, scaffold `~/.claude/skills/<name>/SKILL.md` from the template, open PR to `mphinance/alpha-skills`. \|
12	\| audit \| "skill-forge audit", "skill audit", "/skill-forge", "what skills should I build" \| Run the miner over `~/.claude/projects/*/.jsonl`, present `reports/latest.md`, ask which candidates to forge or refine. \|
13	\| refine \| "refine my skills", "skill-forge refine <name>", "improve the <name> skill" \| Propose additive-only changes (new trigger phrase, new example, new section) to an existing skill. Opens PR with diff. \|
14
15	## Flow
16
17	### forge mode
18
19	1. Ask the user 2-3 questions max: skill name (kebab-case), one-sentence purpose, primary trigger phrase. Don't over-interview.
20	2. Run the scaffolder.
21	```
22	python scripts/forge_new.py --name <name> --brief "<one-sentence purpose>"
23	```
24	The scaffolder reads `templates/SKILL.md.tmpl` and substitutes `{{name}}`, `{{description}}`, `{{title}}`, `{{when_to_invoke}}`, `{{flow}}`, `{{hard_rules}}`.
25	3. Open the freshly written `~/.claude/skills/<name>/SKILL.md`. Review with the user. Tighten copy if needed.
26	4. Publish.
27	```
28	python scripts/publish.py <name>
29	```
30	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.
31
32	### audit mode
33
34	1. Run the miner.
35	```
36	python scripts/mine_chats.py --days 30
37	```
38	2. Read `reports/latest.md` aloud (the markdown report) and `reports/latest.json` (structured candidates).
39	3. Present the three sections: new-skill candidates, refinement candidates, pain points. Ask which to act on.
40	4. For each chosen new-skill candidate, drop into forge mode with `publish.py --from-audit` so the PR body cites the mined evidence.
41	5. For each chosen refinement candidate, drop into refine mode.
42
43	### refine mode
44
45	1. Read the target skill's existing SKILL.md in full. You are not allowed to remove or restructure anything.
46	2. Propose additions only: new trigger phrase in the frontmatter description, new example, new "When NOT to use" bullet, new flow step.
47	3. Write the proposed change to `proposals/<skill-name>/CHANGES.diff` first. Confirm with the user.
48	4. Apply the additive edit to `~/.claude/skills/<skill-name>/SKILL.md`.
49	5. Publish.
50	```
51	python scripts/publish.py <skill-name>
52	```
53	Commit message starts with "Refine <name> skill: <one-line summary>". PR body explains the addition and links the mined evidence.
54
55	## Hard rules
56
57	- Never auto-merge PRs. `publish.py` opens the PR. User merges. No `gh pr merge` ever.
58	- Never restructure existing skills in refine mode. Additive-only. If a skill needs a rewrite, that's a new forge, not a refine.
59	- Refinements are additive-only. No removed lines beyond pure whitespace. `publish.py` enforces this in refine mode.
60	- Never mine recursively on skill-forge's own sessions. The miner already filters self-references. Don't disable it.
61	- Skip SSH transcripts. Project paths starting with `ssh-` or cwd under `/home/` are remote work and not mined.
62	- No em dashes. Use en dash with spaces or commas. No emojis in forged skills.
63	- stdlib only. Forged skills and skill-forge scripts use Python stdlib, no pip installs.
64	- Always go through PR. Never edit files in `~/.cache/skill-forge/alpha-skills/skills/` directly.
65
66	## Scheduling
67
68	The audit is the part you want on a cron. Two options:
69
70	- Preferred – use the `/schedule` skill.
71	```
72	/schedule weekly /skill-forge audit
73	```
74	Runs the audit weekly, writes `reports/latest.md`, notifies you next session.
75
76	- 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.
77
78	Forge and refine modes are interactive by design. Don't schedule those.
79
80	## Out of scope
81
82	- Auto-merging PRs. User merges, always.
83	- In-place edits to

People who liked this also viewed

6 picks

Type