| name | skill-forge |
| description | When Claude discovers a non-obvious solution, unusual pattern, or hard-won
insight during a session, automatically forge it into a new skill. Don't
just note the learning - create the actual skill file so future sessions
benefit immediately. This is the flywheel: work → discovery → skill → smarter
future sessions → repeat.
|
| allowed-tools | bash: ls, cat, mkdir
file: read, write
|
Skill Forge
Knowledge that stays in one session is wasted. When Claude discovers something
non-obvious - a debugging technique, a gotcha, a pattern that works - it should
become a skill automatically. Not "maybe document this later" but "forge it now."
This is the flywheel that makes the skill library self-improving.
When To Activate
Trigger when:
- Claude solves a problem that took multiple attempts
- Claude discovers a non-obvious pattern or gotcha
- A debugging session reveals something others would hit
- User says "we should remember this" or "make this a skill"
- Claude catches itself about to make a mistake it's made before
- A workaround is found for a tool/library limitation
- The solution was counter-intuitive
Do NOT trigger for:
- Obvious solutions anyone would find
- Project-specific knowledge (not generalizable)
- Things already covered by existing skills
- Minor learnings not worth the overhead
Instructions
Step 1: Identify the Insight
Capture what was learned:
Discovery: [One sentence summary]
Context: [What task/problem led to this]
Why non-obvious: [Why someone else would miss this]
Generalizable: [YES/NO - is this useful beyond this specific case?]
If not generalizable, stop - add to breadcrumbs instead, not a skill.
Step 2: Extract the Pattern
Generalize from the specific case:
Specific case: [What happened here]
General pattern: [The reusable insight]
Triggers: [When should future Claude activate this]
Step 3: Draft the Skill
Create the skill structure:
---
name: [kebab-case-name]
description: |
[2-3 sentence description that would trigger activation]
allowed-tools: |
[appropriate tools]
---
# [Skill Name]
<purpose>
[Why this skill exists - the problem it prevents]
</purpose>
## When To Activate
Trigger when:
- [Condition 1]
- [Condition 2]
## Instructions
### Step 1: [First step]
[Instructions]
### Step 2: [Second step]
[Instructions]
## NEVER
- [Anti-pattern 1]
## ALWAYS
- [Required behaviour 1]
## Examples
### Example 1: [Scenario]
[Concrete example]
<failed-attempts>
What DOESN'T work:
- [Failed approach and why]
</failed-attempts>
## Origin
Forged from: [Brief description of the session/problem that spawned this]
Step 4: Write the Skill File
Create the skill directory and file:
skills/[skill-name]/SKILL.md
Step 5: Confirm Creation
Skill forged: [skill-name]
Location: skills/[skill-name]/SKILL.md
Trigger: [When it will activate]
This skill will now be available in future sessions.
Quality Checks
Before forging, verify:
| Check | Requirement |
|-------|-------------|
| Generalizable | Useful beyond this specific project |
| Non-obvious | Not something Claude would naturally do |
| Actionable | Clear instructions, not just "be careful" |
| Triggered | Clear conditions for when to activate |
| Distinct | Not duplicate of existing skill |
Skill Naming Conventions
- Use kebab-case: `cache-invalidation`, not `cacheInvalidation`
- Be specific: `async-cleanup` not `async-stuff`
- Verb or noun that implies action: `trace-imports`, `validate-env`
- Avoid generic names: `helper`, `utils`, `misc`
NEVER
- Forge project-specific knowledge as skills (use breadcrumbs)
- Create skills for obvious things
- Forge without the
<failed-attempts> section (failures teach)
- Create duplicate skills - check existing ones first
- Forge trivial learnings (overhead not worth it)
ALWAYS
- Include the origin story (what spawned this skill)
- Add
<failed-attempts> documenting what doesn't work
- Make triggers specific and unambiguous
- Test that the skill makes sense out of context
- Keep skills focused (one insight per skill)
Examples
Example 1: Debugging Discovery
During debugging, Claude discovers that a React hook was causing infinite
re-renders because of object reference comparison.
Discovery: useEffect with object dependency causes infinite loops
Context: Debugging React component that kept re-rendering
Why non-obvious: Object looks the same but reference changes each render
Generalizable: YES - common React gotcha
Forging skill: react-dependency-check
Resulting skill would include:
- Triggers: React debugging, infinite loops, useEffect issues
- Instructions: Check dependency array for objects/arrays
- Failed attempts: "Tried adding object directly to deps - still loops"
Example 2: API Gotcha
Claude discovers that an API returns different formats based on count
(single object vs array).
Discovery: API returns object for 1 result, array for multiple
Context: Parsing API response failed on single-result queries
Why non-obvious: Only manifests with exactly one result
Generalizable: YES - common API pattern
Forging skill: api-response-normalization
Example 3: Not Worth Forging
Claude fixes a typo in a config file.
Discovery: Config had typo in key name
Generalizable: NO - specific to this project
[Not forging - adding to breadcrumbs instead]
The Flywheel
Session 1: Struggle with problem X
↓
Solve it after 30 min
↓
Forge skill "handle-X"
↓
Session 2: Encounter similar problem
↓
skill-gate activates "handle-X"
↓
Solved in 2 min
↓
Time saved: 28 min
↓
Compound over hundreds of sessions
Integration with Other Skills
- learn-from-this: Analyzes failures, skill-forge turns them into skills
- retrospective: Reviews session, skill-forge captures key learnings
- breadcrumbs: For project-specific notes (not generalizable)
- skill-gate: Ensures forged skills get activated
Why This Skill Exists
Every session, Claude learns things. Most of that knowledge evaporates when
the session ends. Skill-forge captures it.
The goal isn't to document everything - it's to capture the non-obvious wins
that would otherwise need to be rediscovered. Each forged skill is future
time saved.
Build the library. Close the loop. Make the system smarter over time.
