Self-Improving Claude Code Skills (2026)

TL;DR: two skills, two jobs

Both are free, both install in under a minute, and both come from the same GitHub account (Kulaxyz), but they solve opposite problems:

• self-learning-skills watches a session for a hard-won fix — a debugging path, a deploy sequence, a project fact you didn’t know up front — and writes it into a new SKILL.md (Claude Code’s Agent Skills format) so the next session starts already knowing it. It grows your agent’s instructions.
• token-diet installs an always-on directive that trims filler from replies, docs, tests, and tool use — the author’s own Sonnet 5 benchmark shows roughly 31% lower bill on average, 17–54% depending on the session. It shrinks the cost of what your agent already says.

Install both:

npx skills add kulaxyz/self-learning-skills
curl -fsSL https://raw.githubusercontent.com/Kulaxyz/token-diet/main/install.sh | bash

Neither is in the MCP.Directory catalog — both are plain Agent Skills you install directly from GitHub, not MCP servers. If you only came for the numbers, jump to the actual numbers. If you want the honest gaps before you trust either one, jump to what we got wrong.

Why self-editing skills exist

A coding agent’s instructions are static between sessions by default. Every project fact, every debugging detour, every hard-earned “oh, that’s why it fails” evaporates when the session ends, so the next session re-derives it from scratch. That’s the first failure mode: an agent with no mechanism to promote what it just learned into what it will know next time.

The second failure mode is orthogonal: even a well-informed agent tends to over-explain. Preamble, postamble, restating the question, padding a reply past what the answer needed — none of it is wrong, all of it is billed. On a long session, cached re-reads of the growing transcript compound that cost turn over turn.

Both problems share a root cause: nothing routinely edits the agent’s own instruction budget. self-learning-skills and token-diet are both meta-skills — skills whose job is to manage the skill system itself, not a task domain like “write SQL” or “call the Stripe API.” One grows it, one shrinks its running cost. This is a different category from a cookbook skill you invoke for one task, or a curated skill collection you browse for coverage — these two operate on the instruction layer itself.

Mental model: the 5 named pieces

Five pieces carry the whole system. Learn these once and both READMEs stop being new vocabulary.

• Skill (SKILL.md) — a portable, self-describing instruction file that Claude Code and other Agent Skills clients load based on its description field matching the current task. The unit both tools ultimately write or install.
• Golden path — self-learning-skills’ unit of capture: the proven sequence that solved a hard problem, plus the dead ends it ruled out along the way.
• Promotion rule — the three-gate check that decides whether a golden path becomes a durable skill or stays a throwaway note.
• Always-on directive — token-diet’s persistence mechanism: a block of instructions injected into every session automatically, via a Claude Code SessionStart hook (a script the client runs when a session begins), an always-loaded AGENTS.md, or an editor rule file.
• Levels — token-diet’s dial: on (default), lite, ultra, off. A different axis from the model’s own effort level — effort controls how hard the model thinks, levels control how much it writes.

SELF-LEARNING-SKILLS (grows new instructions)
session --> hard-won fix --> promotion rule (3 gates) --> skills/<name>/SKILL.md
                                    | fails a gate
                                    v
                             MEMORY.md note, or skipped
                                    |
                                    v
                     next session loads the skill automatically


TOKEN-DIET (shrinks what's already there)
every session --> SessionStart hook / AGENTS.md / rule file
                          | injects the always-on directive
                          v
        replies . docs . tests . code . context . tools . subagents
                          |
                          v
              same correctness, fewer tokens on the bill

Neither tool touches the model weights or your account settings. Both work by changing what text is sitting in the context window before the model generates — the oldest and most reliable lever a coding agent has.

Install both (verified against the actual repos)

Everything below is copied from each project’s README and install script, read directly from GitHub — not paraphrased from memory.

self-learning-skills

Three install paths. The recommended one goes through the community skills CLI, which the README says auto-detects and installs into whatever agents it finds on your machine:

# this project only, auto-detects agents present
npx skills add kulaxyz/self-learning-skills

# global -- every project on this machine
npx skills add kulaxyz/self-learning-skills -g

# one specific agent
npx skills add kulaxyz/self-learning-skills -a claude-code

# try it once without installing anything
npx skills use kulaxyz/self-learning-skills --skill self-learning | claude

Or as a Claude Code plugin:

/plugin marketplace add kulaxyz/self-learning-skills
/plugin install self-learning@self-learning-skills

Manual install copies one directory: cp -R self-learning-skills/skills/self-learning ~/.claude/skills/ for Claude Code, a .cursor/rules/self-learning.mdc file for Cursor, or an AGENTS.md append for Codex, Zed, Aider, and Gemini CLI. Where a skill or fix is project-specific, install into the repo’s own .claude/skills/ instead so it ships to teammates via git.

token-diet

One installer, run directly or piped through curl:

# auto-detects Claude Code / Codex, installs the default (quality-locked) level
curl -fsSL https://raw.githubusercontent.com/Kulaxyz/token-diet/main/install.sh | bash

# the aggressive telegraphic level -- see "Levels" below before you reach for this
curl -fsSL https://raw.githubusercontent.com/Kulaxyz/token-diet/main/install.sh | bash -s -- --ultra

Useful flags, read straight from install.sh: -a claude|codex|cursor|windsurf|cline|all|print targets one agent (or prints the raw directive to paste anywhere yourself); --project installs into the current repo instead of your global config; --uninstall removes it cleanly. Once installed, toggle at runtime without reinstalling: /token-diet [on|lite|ultra|off].

self-learning-skills, deep dive

The README frames it exactly right: “it’s a meta-skill: it doesn’t do the work, it captures how the work got done.” Four mechanics make that concrete.

Recognize the moment

The skill’s trigger description tells Claude Code to watch for cues, unprompted: a task that only worked after several attempts, a project fact nobody told the agent up front (where the prod DB lives, the deploy command, a required order of operations), an operational workflow likely to recur, or the user simply saying “remember this.” It acts immediately on any of these — it does not wait to be asked.

Triage: skill, memory, or skip

Not every lesson earns a whole skill file. The README is explicit about routing by shape:

The promotion rule

This is the mechanism keeping the whole system honest. “A skill is authoritative — the next session trusts it without re-deriving it,” so promotion holds a high bar. All three gates must pass:

1. A passing check — the path was actually verified: a test passed, a clean exit, a green build, a reproduced repro. “Seemed to work” doesn’t count.
2. A named failure pattern — the specific failure the path avoids or diagnoses, not a vague “sometimes it breaks.”
3. At least one ruled-out dead end — a concrete approach that was tried and eliminated, with the reason why.

Miss any one and the session stays a tentative memory note, or gets skipped — it does not become a skill. The README credits this rule to community feedback, and the harvested-skill template enforces it structurally: every generated SKILL.md has required Failure pattern and Verified by fields with an explicit comment — “if you can’t [fill both lines], this shouldn’t be a skill.”

---
name: REPLACE-with-skill-name-matching-this-directory
description: >
  REPLACE. One short paragraph. Say WHAT the skill does AND WHEN to use it.
license: MIT
---

# REPLACE -- title of the golden path

**Failure pattern:** REPLACE -- the failure this path avoids or diagnoses.
**Verified by:** REPLACE -- the passing check that confirmed it. Not "seemed to work".

## Procedure
- [ ] 1. REPLACE -- first step (exact command / path if fragile).
- [ ] 2. REPLACE -- next step, with the required order if it matters.
- [ ] 3. REPLACE -- how to verify it worked.

## Gotchas
- REPLACE -- a non-obvious fact that defies the reasonable assumption.

## What didn't work
- REPLACE -- approach that looked right but failed, and the reason.

That last section — What didn’t work — is the part most tools skip. Capturing the ruled-out dead ends, not only the winning path, is often worth more than the fix itself: it stops next session from re-walking the same wrong turn.

Delegate the write, keep it boxed in

Where the client supports it (Claude Code: a skill with context: fork), the harvest is delegated to a subagent — a process that inherits the current conversation, since the golden path only exists in that transcript. The brief handed to it is deliberately narrow: write only under the skills directory, don’t touch project source, don’t resume the original task, never write a secret value, report the path and a one-line summary, then stop. Elsewhere it runs inline. Either way, our take: the constrained brief matters more than the delegation mechanism — a writer this narrowly scoped can’t do much damage even if it misjudges what to capture.

token-diet, deep dive

token-diet’s SKILL.md organizes its rules into seven lettered buckets. The framing that matters most is buried in the middle of the file, not the headline: “input tokens recur — the transcript and every tool output are re-sent each turn. So keeping junk out of context outweighs shortening what you type.”

The seven buckets, condensed

• A — Talking to the user. Lead with the answer, no preamble or postamble, report deltas not narration.
• B — Written artifacts. Docs, memory, hand-offs, plans, comments: minimum words that still say everything.
• C — Tests. Key and critical/edge paths only, grouped, capped at 10 per session — money, auth, and data-loss coverage is never cut.
• D — Code. YAGNI (build only what’s asked), concise but idiomatic, never cryptic, no dead code.
• E — Context & search. Grep before you read, never open a file blind, batch reads, never re-read a file you just edited. Marked as the highest-leverage bucket because cache read and cache write — Anthropic’s billing categories for reused vs. newly cached context — dominate a long session’s bill.
• F — Tools & flow. Batch independent calls into one turn, stop the instant you can act.
• G — Sub-agent instructions.Delegate broad, bounded search to a cheaper model; keep correctness-sensitive verification on your own model.

Levels: on, lite, ultra, off

on is every rule above and is the default after install. lite restricts itself to buckets A and B — communication and written artifacts only, tooling untouched. ultra adds telegraphic output on low-stakes surfaces: chat replies and status notes drop articles, auxiliaries, and pronouns where meaning survives. High-stakes surfaces — code, commands, file paths, identifiers, error strings, tests, docs, and sub-agent instructions — are explicitly exempt and stay fully precise even under ultra. The rule of thumb from the SKILL.md itself: “if a human reads it and moves on, telegraph it; if a human or agent must act on it exactly, keep it whole.”

Their own before/after, measured with a real tokenizer:

Same fix, same identifiers, same file path — only the filler is gone. That distinction (never touching an identifier, a path, or a command) is the difference between this and a blunter compression tool; it’s also why the guardrails below exist as a hard floor, not a suggestion.

Guardrails that don’t bend for tokens

Four rules the skill states it will never trade away: never drop below critical test coverage (money, auth, data-loss paths always verified); concision applies to output, never to the reasoning needed for correctness; code, commands, identifiers, and error strings stay verbatim; and never cryptic — readable-and-short beats short-and-obscure.

The hook that silently failed on new sessions

A skill body normally loads on demand — only when its description matches. To make token-diet apply on every turn, the installer injects the directive through a channel that fires automatically each session: a Claude Code SessionStart hook (Codex gets an always-loaded AGENTS.md; Cursor, Windsurf, and Cline get an always-on rule file). The README credits the same trick to caveman, an earlier project.

Reading install.sh directly turns up a fix the README doesn’t mention: the Claude Code hook now emits its directive as structured JSON, not plain text, and the script’s own comment explains why — plain stdout from a hook is “only reliably added on resume, so a cat hook silently no-ops on new sessions.”

exec python3 -c 'import json,sys; print(json.dumps({"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":open(sys.argv[1]).read()}}))' "$root/token-diet/activation.md"

That gets registered in Claude Code’s settings.json as a command hook shaped like this:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"/Users/you/.claude/hooks/token-diet-sessionstart.sh\""
          }
        ]
      }
    ]
  }
}

The commit that landed this fix is dated July 4, 2026, one day after the repo’s first commit. If you happened to install in that first 24-hour window, reinstalling costs one command and guarantees you’re on the working version. It’s a small window, but it’s exactly the kind of gap that’s invisible until you go looking — the skill would have silently done nothing on any session that wasn’t a resume.

What we got wrong

Three assumptions we walked in with, corrected by actually reading the source instead of the marketing line in each README.

We assumed “≈31% lower bill” meant every session. It’s an unweighted average across three very different scenario types in the author’s own benchmark. The bill savings actually range 17–54%, and the project’s own results file is unusually candid about this: an early sample suggested 31% bill savings on a code-change task, but a larger re-run showed that was “favorable cache variance” and the reproducible figure is closer to 22%. That kind of self-correction, published rather than quietly dropped, raised our confidence in the rest of the numbers.

We assumed both repos carried the same license. They don’t. self-learning-skills has a LICENSE file and is MIT. token-diet, as of this writing, has no LICENSE file at all — we checked the repo contents directly, not just the README. That’s a real gap if you plan to fork or redistribute it rather than just run the published installer.

We assumed a self-authoring skill was inherently safe because it says “never write secrets.” A prose rule doesn’t catch a pasted API key re-typed into a “what the client does” description, or a placeholder like YOUR_TOKEN_HERE that a hook later fills in. An open pull request against self-learning-skills exists specifically because a contributor hit both failure modes in a private automation stack. The base rule is right; it just isn’t sufficient on its own yet.

Right way / wrong way

Common mistakes

• Trusting a harvested skill without reading it. Root cause: there is no built-in review step between a skill being written and it becoming active — an open GitHub issue on self-learning-skills proposes adding one. Until then, treat your skills/ folder like generated code: skim what landed.
• A pasted secret ending up in a skill file. Root cause: the “never write secret values” rule is prose, and prose doesn’t pattern-match a Bearer token, a database connection string, or a placeholder a hook fills in later. This is precisely why the pending PR adds a literal pre-write filter for token-shaped strings and DSNs.
• token-diet silently doing nothing on a fresh session. Root cause: the original SessionStart hook emitted plain stdout, which Claude Code only reliably injects on resumed sessions. Fixed July 4, 2026 — see above.
• Expecting the 31% number on a heavy refactor. Root cause: bill savings are floored by cache write (re-reading source to make a correct change), which caps code-change tasks near 22–28% even though output itself drops much further.
• Duplicate skills competing to trigger. Root cause: skipping the harvest procedure’s dedupe step. The SKILL.md explicitly calls for checking existing skills and the memory index before writing a new one — update, don’t duplicate.

The actual numbers

token-diet is the one of the two with quantified claims, so it’s the one worth scrutinizing. The author’s benchmark (Sonnet 5, real agentic runs against a shallow clone of nestjs/nest, baseline vs. skill, small sample sizes of 2–4 runs per arm) breaks down by session type:

A separate output-only micro-benchmark, measured with a real tokenizer across five artifact types (prose, tests, a plan, a hand-off doc, a sub-agent instruction), found roughly 36% average output reduction, rising to 35–56% on the verbose-prone ones — plans, docs, hand-offs, sub-agent prompts. The project also ran one lever that backfired and says so directly: delegating a 20-call-site verification pass to a weaker model to save money roughly doubled the bill instead, because the weaker model over-explored the open-ended check across 34–72 turns. That result is now encoded as a guardrail in bucket G — delegate bounded search downward, keep correctness-sensitive verification on the strong model.

All of this is self-reported by the author, reproducible via ANTHROPIC_API_KEY=… node bench/bench.mjs, and not independently re-run by us or anyone else we found. Small sample sizes (n=2 to n=4 per arm) mean the specific percentages will move if you reproduce them. The pattern — output-heavy sessions save far more than code-change sessions — is the more durable takeaway than any single percentage.

Who this is for

• self-learning-skills fits you if you run Claude Code, Cursor, or an AGENTS.md-reading agent against the same repo(s) repeatedly, and you’re tired of re-explaining project quirks every session.
• token-diet fits you if you’re cost -sensitive about Sonnet 5 usage and your sessions skew toward chat, planning, or explanation rather than constant file editing — that’s where the 54% ceiling actually lives.
• Skip both if you need governed, reviewed instruction changes (no approval flow exists yet for self-learning-skills) or you want a single guaranteed savings number rather than a range that depends on your own session mix.

Community signal

Both projects are weeks old — self-learning-skills shipped June 28, 2026; token-diet shipped July 3 — so there isn’t a large public track record yet. What exists is worth reading in full rather than skimming past.

self-learning-skills was posted to Hacker News on June 29 (“Self-learning skill for Claude: let the agent capture its own hard-won patterns”); it drew a handful of points and no thread discussion there. The real engagement happened on GitHub. One contributor, who says they found the project via that HN post, opened an issue proposing a review step — the sharpest critique either repo has received:

“A session correction may be valid only for this repo, this environment, or this one task, but once written as an auto-loaded skill it becomes durable behavior… auto-learning needs provenance and replay checks, not just a good generated skill body.”

That issue (still open) proposes a LESSON_RECEIPT.md or --dry-run review mode before a harvested lesson goes live. A second, complementary pull request (also open) adds a literal pre-write filter for token-shaped secrets and connection strings — distinct from the receipt idea, and explicit that it doesn’t replace it. Neither has merged as of this writing. We couldn’t find a Reddit thread about either project yet — a fair signal of how early this is, not evidence the tools don’t work.

token-diet has picked up smaller organic shares outside English-language channels this week, including this technically accurate summary (translated from Chinese) linking straight to the repo:

Translated: a Shell-based token-optimization skill for five coding agents, cutting tokens across seven areas, averaging about 31% lower token use with 30–81% less output and no loss of correctness — an accurate restatement of the README, not embellished. We found no first-party or maintainer post from the author on X for either project; the GitHub profile lists no Twitter handle.

The verdict

Neither tool is dangerous by default — both ship real guardrails (the promotion rule, the never-cryptic / never-below-critical-coverage rules). The honest risk is ordinary software risk: young, small, unaudited, easy to outgrow your own review habits once it’s working quietly in the background.

The bigger picture

These two sit at the edge of a pattern showing up across the Claude Code skills ecosystem: skills that operate on the skill system itself, not on a task domain. That’s a different axis than a large curated skill collection (breadth of coverage) or fixing why an existing skill won’t activate (getting a known skill to fire) — this is about which skills get created in the first place, and what they cost to keep around. Paired with the model’s own effort-level dial, you end up with two independent cost levers: how hard the model thinks, and how much it writes down.

The open review-receipt proposal on self-learning-skills is worth watching specifically. If provenance and replay checks for auto-harvested skills become a common pattern — or get folded into the underlying Agent Skills standard itself — that closes the one real gap in an otherwise well-thought-out design. Until then, the discipline is on you: read what gets harvested, and don’t install either tool somewhere you wouldn’t read the diff.

Frequently Asked Questions

Glossary

Sources

• Primary — self-learning-skills repo, README, SKILL.md, skill-authoring reference, and template: github.com/Kulaxyz/self-learning-skills (MIT)
• Primary — token-diet repo, README, SKILL.md, install.sh, and bench/RESULTS.md: github.com/Kulaxyz/token-diet (no LICENSE file found as of this writing)
• Primary — the install CLI self-learning-skills depends on: github.com/vercel-labs/skills
• Community — open GitHub issue proposing a review-receipt step: “Add a review receipt before auto-harvested skills become durable”
• Community — open pull request adding a pre-write secret filter: “docs(self-learning): add literal pre-write secret self-audit checklist”
• Community — Hacker News launch thread: “Self-learning skill for Claude”, June 29, 2026
• Community — verified reaction tweet: @QingQ77, July 6, 2026
• Related guides: Claude Code Effort Levels Explained · Claude Code Skills: The Developer Guide · Matt Pocock’s Skills: The npm Moment · Why Your Claude Skill Won’t Activate · What is MCP?
• On MCP.Directory: Browse the skills catalog · Claude Code client reference