Skill Forge

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:

Skill Naming Conventions

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.

skill-forge