self-learning-skills Turns Agent Mistakes Into Repo-Resident Wisdom

A meta-framework that teaches coding agents to harvest golden paths, reject lucky guesses, and write only the lessons worth keeping.

8 min read • View on GitHub • More from Kulaxyz

A coding agent sits at a desk beside a split repository drawer. On one side is a messy stack of failed terminal attempts and scattered command notes. On the other side, a clean Markdown rule is being filed behind a small checkpoint gate, showing that only proven lessons enter the repo. The scene explains that this project promotes hard-won knowledge instead of merely storing session noise. — The core idea is not passive memory. It is promotion, with a gate.

Key Takeaways

This repo turns successful debugging into versioned instruction files, so future sessions inherit proven workflows instead of re-discovering them.
Its central discipline is a promotion gate that refuses lucky guesses and only preserves lessons backed by a green build, a named failure, and a ruled-out dead end.
The project is less a memory layer than a triage system, separating durable skills from one-line facts and one-off skips.
Its real bet is that coding agents should maintain their own playbooks the same way teams maintain CI, Dockerfiles, and repo conventions.

The strange idea at the center of the repo

Most agent memory tools ask a simple question: what should we retrieve later? self-learning-skills asks a sharper one: what deserves to survive at all? That shift matters because the average coding session is full of false positives, local quirks, and lucky guesses that should die with the run.

I built self-learning-skills because I noticed my agents often spent time poking around and guessing at things I had already solved in previous runs. I used to manually copy-paste those fixes into future prompts or backport them into my skills. This repo streamlines that workflow.

Scott Falconer (as 'bantler'), Project Creator · Letting agent skills learn from experience : r/ClaudeAI - Reddit

That is the project’s real promise. It does not just remember. It teaches an agent to recognize when a solution has earned the right to become part of the repo, so the next run starts with something better than hope.

How an agent decides what deserves to be remembered

The repository’s triage logic lives in SKILL.md and related adapter files. The distinction is simple but strict: a multi-step procedure becomes a skill, a narrow fact becomes memory, and a one-off or noisy detail gets skipped. That is anti-bloat logic disguised as instruction engineering.

The pipeline turns a temporary discovery into a reusable repository asset only after it clears a discipline gate.

## Triage

- **Skill**: a repeatable, multi-step procedure worth codifying.
- **Memory**: a compact fact or constraint worth recalling.
- **Skip**: a one-off detail that should not pollute the repo.

## Capture rule

Only promote knowledge that is proven, specific, and reusable.

The promotion gate is the real product

The sharpest part of the system is not the storage format. It is the gate. Before a lesson gets written back into the repo, the agent has to show a green build, name the failure that motivated the fix, and rule out at least one dead end. That is how the project blocks hallucinated certainty from becoming permanent policy.

A close-up mechanical sorting machine with three input chutes labeled skill, memory, and skip. Cards fall in from above, but only the card marked by a green check, a named failure, and a ruled-out dead end is stamped and routed into the skill chute. The image explains the repo's discipline gate and why only proven workflows are promoted. — Only the hard-won path gets stamped and filed.

That matters because agent memory is otherwise too eager to generalize from a single success. This repo insists on proof, not vibes. It is trying to encode judgment, not just text.

Why the template matters more than the rule

The template file is where the idea becomes durable. Instead of dumping prose into a note, it separates procedure, gotchas, and what did not work. That structure makes the learned output readable to humans and actionable for future agents.

# Procedure
1. Run the verified commands.
2. Check the result.
3. Capture the reusable path.

# Gotchas
- Non-obvious environment details.
- Project-specific quirks.

# What didn't work
- Failed commands.
- Dead ends that should not be repeated.

That schema is doing more than documentation. It is compressing experience into a format that can be copied across adapters without losing the point. The repo is teaching an agent how to write for its future self.

The interoperability story: one idea, four adapters

Surface	What it is	Why it matters
Cursor rules	.mdc files that stay always on	Good for persistent editor-level behavior
Agent Skills	Standards-based SKILL.md packaging	Makes the idea portable across supported agents
AGENTS.md	Plain repo-level instruction file	Lowest-friction fallback for broad compatibility
Claude plugin	Manifest-driven distribution	Turns the same idea into an installable package

This is the distribution strategy hidden inside the repo. The same discipline can be delivered through Cursor, Agent Skills, plain AGENTS.md usage, or a Claude plugin. That makes the project less like a single tool and more like a portable operating pattern.

Why this beats generic memory frameworks

Approach	What it optimizes for	What it misses
Generic memory frameworks like Mem0, Letta, Zep, and Cognee	Retrieval, personalization, broad long-term context	They can preserve too much and still not guarantee the right lesson lands in the right place
Manual rules like Cursor Rules or AGENTS.md	Static persistence	They depend on humans remembering to curate them
self-learning-skills	Promotion of proven workflows at the moment they become useful	It is narrower than a full memory layer, but stricter about quality

The distinction is subtle but important. Generic memory systems try to help agents recall later. This repo tries to make sure the thing worth recalling gets committed in the first place. That is a much smaller surface area, but a much stronger editorial filter.

The bigger bet: agents that maintain their own playbooks

The long-term idea here is bigger than prompting. It is repo culture for agents. If a workflow was hard to discover, it should be written down. If it was only accidentally correct, it should be discarded. If it is reusable, it should become part of the operating manual.

That is a familiar pattern in software teams. CI encodes trust. Dockerfiles encode environment. Repo conventions encode taste. self-learning-skills argues that agent learning should be treated the same way: as a governed artifact, not a private hallucination in a chat window.