SKILL.md — The Self-Improving Claude Code

Look at your current AI setup. You write a brilliant prompt. It works perfectly on Monday. But by Friday? A framework updates. A new pattern emerges. Your prompt is dead. It is rotting on your hard drive! This is a tragedy of static configuration.

We are going to fix this today. Not by writing more prompts. By building a system that learns.

This repository contains drop-in Claude Code components that make your setup self-improving. I will demonstrate the flagship command: /learn.

Watch what happens when we unleash this system on the real world:

/learn https://svelte.dev/docs/kit          # We feed it documentation!
/learn ~/docs/architecture.md               # We feed it local designs!
/learn ~/.claude/plugins/marketplaces/      # We absorb other skills!
/learn ~/projects/my-api                    # We extract patterns from living code!

Read the SvelteKit 5 migration guide? Your sveltekit-patterns skill now knows about runes. Discovered a new Express middleware pattern? Your api-middleware skill just got smarter. It adapts!

The Architecture: Three Fundamental Layers

If you put everything in one file, the system collapses into chaos. We must have a profound separation of concerns. Three layers. Each doing exactly one thing. It is beautiful!

flowchart TD
    Source["/learn &lt;source&gt;"] --> Command
    
    subgraph Architecture ["Three layers, each doing one thing well"]
        Command["COMMAND (26 lines)<br/><i>Thin trigger. Delegates everything to the specialist.</i>"]
        Agent["AGENT (skill-learning-specialist)<br/><i>The orchestrator. Handles URLs, directories, repos.<br/>Manages the approval loop. Doesn't contain methodology.</i>"]
        Skill["SKILL (skill-learning)<br/><i>The brain. 7-phase workflow. Novelty detection.<br/>Matching algorithm. CLEAR validation. All the methodology.</i>"]
        
        Command --> Agent
        Agent --> Skill
    end

    classDef default fill:#1a1a1a,stroke:#333,stroke-width:1px,color:#fff,text-align:left
    classDef source fill:none,stroke:none,color:#58a6ff,font-weight:bold
    class Source source

The Law of Separation: Commands trigger! Agents orchestrate! Skills contain the methodology!

Why does this matter? Because commands must stay tiny. Agents must handle the messy, unpredictable real world (blocked URLs, missing directories). And the Skills—the brains—must hold pure, reusable knowledge that any agent can load. You must not mix them!

The Experiments: What `/learn` Can Do

Let us run some experiments.

Experiment 1: The Documentation

/learn https://docs.example.com/guide

It fetches the page. It extracts the technical patterns. It matches them to your existing skills. It shows you the diff, and upon your approval, it permanently alters its own brain.

Experiment 2: The Living Codebase

/learn ~/projects/my-api

Are you tired of explaining your repo's conventions over and over? Point it here! It detects the project type. It finds your schemas, your middleware, your presets. It extracts your unique patterns and creates a new skill from what it finds.

Experiment 3: The Marketplace

/learn ~/.claude/plugins/marketplaces/my-skills/

It discovers skills via AGENTS.md manifests or glob patterns. You choose: copy skills wholesale, or extract their insights to enhance your own.

The Demonstration of Skill Judgment

If you feed an AI everything, you teach it nothing! You bloat its context! You drown the signal in noise!

How do we prevent this? We use a strict, unforgiving filter: Novelty + Leverage. When /learn reads a document, it asks two critical questions:

"Does the source teach something not already encoded?"
"Will preserving this change future agent behavior?"

We divide all knowledge into four tiers. Pay close attention to Tier 1:

Tier	Status	What It Means
1	REJECTED!	Training data. The model already knows it. We throw it away!
2	CANDIDATE	Implementation details. The precise how.
3	STRONG CANDIDATE	Architectural trade-offs. The why.
4	HIGHEST SIGNAL	Counter-intuitive. Contradicts standard assumptions.

But novelty alone is not enough. A fact can be new and still useless. So every Tier 2-4 candidate must pass the leverage test:

Leverage	What It Means
0-1	Interesting, but unlikely to change future work. Reject it.
2	Reusable detail: a command, flag, schema, convention, or implementation move.
3	Workflow-changing: affects placement, safety, validation, or debugging behavior.
4	Failure-preventing: avoids contradiction, data loss, security risk, or expensive rework.

Only insights that are both novel and behavior-changing enter a skill. If an insight conflicts with old guidance, /learn should replace, qualify, split, or skip it. If it makes old guidance stale, the proposal should delete as well as add.

That is the deeper law: learning must preserve density. A self-improving skill system cannot only accumulate. It must also prune.

So every learned rule needs enough metadata to be inspected later:

<!-- Learned: 2026-05-16 from https://example.com/source -->

Those markers make skill health visible: stale rules, duplicate patterns, missing sources, and sections that have grown too large. When /learn finds a domain with no home, it should create a structured stub with triggers, workflow, validation, and provenance, not an empty file.

The system works when the skill gets sharper, not merely longer.

The Laboratory Setup (Installation)

How do you build this in your own laboratory?

Option 1: The Quick Start
Each example mirrors the exact ~/.claude/ structure. You simply copy them over!

# Install the /learn command into your environment
cp -r examples/learn/commands/* ~/.claude/commands/
cp -r examples/learn/agents/* ~/.claude/agents/
cp -r examples/learn/skills/* ~/.claude/skills/

Option 2: The Meta Experiment
Point /learn at this very repository. Let the system learn how to build itself!

/learn ~/path/to/SKILL.md/examples/learn/

We Must Verify Our Results!

We are not guessing here! You must lint your components before committing. We use cclint:

# Install the instrument
go install github.com/dotcommander/cclint@latest

# Run the verification!
cclint ~/.claude/

It catches schema violations. It catches bloated agents. It ensures our fundamental laws are not broken. Every example in this repository passes cclint. It must balance!

Contributing & Credits

Found a pattern worth sharing? Run your own experiments!

Fork this repository.
Add your discovery to examples/.
Follow the format.
Run cclint to verify your results.
Submit a PR.

Credits:

cclint — The Claude Code component linter by @dotcommander

License: MIT. Remix it. Improve it.

Static prompts rot. Self-improving configurations live forever.