Skill Forge

<purpose> 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. </purpose>

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:

code

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:

code

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:

markdown

---
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:

code

skills/[skill-name]/SKILL.md

Step 5: Confirm Creation

code

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:

<quality-checks> | 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 | </quality-checks>

Skill Naming Conventions

<naming> - 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` </naming>

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.

code

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).

code

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.

code

Discovery: Config had typo in key name
Generalizable: NO - specific to this project

[Not forging - adding to breadcrumbs instead]

The Flywheel

code

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.