Build Self-Evolving Skills for Claude Code: The GitHub Pattern That Grows Smarter With Use

The Problem: Static Skills Waste Discovered Knowledge

Traditional Claude Code Skills are static packages. You invoke them, they run, and any domain knowledge discovered during execution—database relationships, codebase patterns, business rules—vanishes when the session ends. Every new conversation starts from zero, forcing Claude to rediscover what you already learned.

This pattern solves that by creating Skills that evolve through use, accumulating validated knowledge in a structured way without becoming bloated or inaccurate.

The Core Architecture: Living Knowledge Base

The pattern organizes Skills into three layers:

skill-name/
├── SKILL.md              # Trigger conditions + governance protocol
├── scripts/              # Execution tools
│   ├── core/            # Computation layer (decay model)
│   ├── decay_engine.py  # CLI for knowledge management
│   └── *.py             # Domain-specific tools
└── references/          # Living knowledge base (AI-maintained)
    ├── _index.md        # Routing table (<40 lines)
    └── <topic>.md       # Topic files with decay-tagged entries

The references/ directory is the key innovation. It's a knowledge base that Claude maintains itself, with entries that have confidence scores that decay over time unless validated.

The Five Gates: Preventing Knowledge Rot

Every piece of discovered knowledge must pass through five gates before being added:

1. VALUE: Is this reusable across sessions? (One-time results are rejected)
2. ALIGNMENT: Does it contradict existing knowledge? (Contradictions trigger corrections)
3. REDUNDANCY: Is this already captured? (Duplicates are merged or skipped)
4. FRESHNESS: How long does this knowledge remain valid?
5. PLACEMENT: Where in the knowledge graph does this belong?

The freshness gate uses a decay model with six knowledge types:

• schema (slow decay)
• business_rule (slow decay)
• tool_experience (medium decay)
• query_pattern (medium decay)
• data_range (fast decay)
• data_snapshot (fast decay)

Each entry gets a decay tag:

<!-- decay: type=schema confirmed=2026-03-15 C0=1.0 -->

How To Use Knowledge: Confidence-Based Trust

Before using stored knowledge, the Skill calculates its current confidence C(t) based on time elapsed and feedback history:

• TRUST (C >= 0.8): Use directly
• VERIFY (0.5 <= C < 0.8): Use but flag for verification
• REVALIDATE (C < 0.5): Verify with tools first

After operations that used knowledge, you provide feedback:

• Success → record positive feedback (slows future decay)
• Failure → record negative feedback (accelerates decay)
• After revalidation passes → reset to fresh state

When To Build Self-Evolving Skills

Ask these two questions about your domain:

1. Will domain knowledge grow through use? (Database schemas, API patterns, business logic)
2. Does that growth have a natural ceiling? (Not infinite expansion)

If both answers are yes, this pattern fits. Ideal use cases:

• Database investigation and schema discovery
• Legacy codebase analysis and pattern extraction
• Business system integration with evolving APIs
• Data pipeline optimization with learned patterns

Getting Started: The Decay Engine CLI

The pattern includes a Python CLI (decay_engine.py) with these commands:

# Initialize a new knowledge base
python decay_engine.py init --skill-name database-investigator

# Scan and update confidence scores
python decay_engine.py scan

# Provide feedback on knowledge entries
python decay_engine.py feedback --entry-id schema.users --positive

# Reset an entry to fresh state
python decay_engine.py reset --entry-id business_rule.invoice_validation

# Inject new knowledge (goes through all five gates)
python decay_engine.py inject --text "Users table has email column with UNIQUE constraint" --type schema

# Search knowledge base
python decay_engine.py search --query "user table constraints"

Example: Database Investigation Skill

Your SKILL.md might define triggers like:

TRIGGERS:
- "analyze the database schema"
- "what tables are related to users?"
- "show me foreign key relationships"

GOVERNANCE:
- Always check references/_index.md first
- Use confidence thresholds: TRUST >= 0.8
- Record feedback after each query execution

When Claude discovers a new foreign key relationship, it runs through the five gates, adds it to references/schema.md with a decay tag, and future sessions can immediately use that knowledge without rediscovery.

The Result: Skills That Get Better With Age

This pattern transforms Claude Code Skills from static tools into learning systems. Each interaction makes them more knowledgeable about your specific domain, reducing repetitive context and increasing accuracy over time. The decay model ensures they don't become bloated with outdated information, maintaining relevance through continuous validation.

For domains where knowledge accumulates but has structure, this is how you build Skills that truly evolve with your needs.