skill-forge

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.