selftune

Self-improving skills for AI agents.

Your agent skills learn how you work. Detect what's broken. Fix it automatically.

Install · Use Cases · How It Works · Commands · Platforms · Docs

---

Your skills don't understand how you talk. You say "make me a slide deck" and nothing happens — no error, no log, no signal. selftune watches your real sessions, learns how you actually speak, and rewrites skill descriptions to match. Automatically.

Works with Claude Code (primary). Codex, OpenCode, and OpenClaw adapters are experimental. Zero runtime dependencies.

Install

npx skills add selftune-dev/selftune

Then tell your agent: "initialize selftune"

Two minutes. No API keys. No external services. No configuration ceremony. Uses your existing agent subscription. You'll see which skills are undertriggering.

CLI only (no skill, just the CLI):

npx selftune@latest doctor

Before / After

selftune learned that real users say "slides", "deck", "presentation for Monday" — none of which matched the original skill description. It rewrote the description to match how people actually talk. Validated against the eval set. Deployed with a backup. Done.

Built for How You Actually Work

I write and use my own skills — Your skill descriptions don't match how you actually talk. Tell your agent "improve my skills" and selftune learns your language from real sessions, evolves descriptions to match, and validates before deploying. No manual tuning.

I publish skills others install — Your skill works for you, but every user talks differently. selftune ships skills that get better for every user automatically — adapting descriptions to how each person actually works.

I manage an agent setup with many skills — You have 15+ skills installed. Some work. Some don't. Some conflict. Tell your agent "how are my skills doing?" and selftune gives you a health dashboard and automatically improves the skills that aren't keeping up.

How It Works

A continuous feedback loop that makes your skills learn and adapt. Automatically. Your agent runs everything — you just install the skill and talk naturally.

Observe — Hooks capture every query and which skills fired. On Claude Code, hooks install automatically during selftune init. Backfill existing transcripts with selftune ingest claude.

Detect — Finds the gap between how you talk and how your skills are described. You say "make me a slide deck" and your pptx skill stays silent — selftune catches that mismatch. Real-time correction signals ("why didn't you use X?") are detected and trigger immediate improvement.

Evolve — Rewrites skill descriptions — and full skill bodies — to match how you actually work. Cheap-loop mode uses haiku for the loop, sonnet for the gate (~80% cost reduction). Teacher-student body evolution with 3-gate validation. Automatic backup.

Watch — After deploying changes, selftune monitors skill trigger rates. If anything regresses, it rolls back automatically.

Automate — Run selftune cron setup to install OS-level scheduling. selftune syncs, evaluates, evolves, and watches on a schedule — no manual intervention needed.

What's New in v0.2.0

• Full skill body evolution — Beyond descriptions: evolve routing tables and entire skill bodies using teacher-student model with structural, trigger, and quality gates
• Synthetic eval generation — selftune eval generate --synthetic generates eval sets from SKILL.md via LLM, no session logs needed. Solves cold-start: new skills get evals immediately.
• Cheap-loop evolution — selftune evolve --cheap-loop uses haiku for proposal generation and validation, sonnet only for the final deployment gate. ~80% cost reduction.
• Batch trigger validation — Validation now batches 10 queries per LLM call instead of one-per-query. ~10x faster evolution loops.
• Per-stage model control — --validation-model, --proposal-model, and --gate-model flags give fine-grained control over which model runs each evolution stage.
• Auto-activation system — Hooks detect when selftune should run and suggest actions
• Enforcement guardrails — Blocks SKILL.md edits on monitored skills unless selftune watch has been run
• Live dashboard server — selftune dashboard --serve with SSE auto-refresh and action buttons
• Evolution memory — Persists context, plans, and decisions across context resets
• 4 specialized agents — Diagnosis analyst, pattern analyst, evolution reviewer, integration guide
• Sandbox test harness — Comprehensive automated test coverage, including devcontainer-based LLM testing

Commands

Your agent runs these — you just say what you want ("improve my skills", "show the dashboard").

Group	Command	What it does
	selftune status	See which skills are undertriggering and why
	selftune orchestrate	Run the full autonomous loop (sync → evolve → watch)
	selftune dashboard	Open the visual skill health dashboard
	selftune doctor	Health check: logs, hooks, config, permissions
ingest	selftune ingest claude	Backfill from Claude Code transcripts
	selftune ingest codex	Import Codex rollout logs (experimental)
grade	selftune grade --skill <name>	Grade a skill session with evidence
	selftune grade baseline --skill <name>	Measure skill value vs no-skill baseline
evolve	selftune evolve --skill <name>	Propose, validate, and deploy improved descriptions
	selftune evolve body --skill <name>	Evolve full skill body or routing table
	selftune evolve rollback --skill <name>	Rollback a previous evolution
eval	selftune eval generate --skill <name>	Generate eval sets (--synthetic for cold-start)
	selftune eval unit-test --skill <name>	Run or generate skill-level unit tests
	selftune eval composability --skill <name>	Detect conflicts between co-occurring skills
	selftune eval import	Import external eval corpus from SkillsBench
auto	selftune cron setup	Install OS-level scheduling (cron/launchd/systemd)
	selftune watch --skill <name>	Monitor after deploy. Auto-rollback on regression.

Full command reference: selftune --help

Why Not Just Rewrite Skills Manually?

Approach	Problem
Rewrite the description yourself	No data on how users actually talk. No validation. No regression detection.
Add "ALWAYS invoke when..." directives	Brittle. One agent rewrite away from breaking.
Force-load skills on every prompt	Doesn't fix the description. Expensive band-aid.
selftune	Learns from real usage, rewrites descriptions to match how you work, validates against eval sets, auto-rollbacks on regressions.

Different Layer, Different Problem

LLM observability tools trace API calls. Infrastructure tools monitor servers. Neither knows whether the right skill fired for the right person. selftune does — and fixes it automatically.

selftune is complementary to these tools, not competitive. They trace what happens inside the LLM. selftune makes sure the right skill is called in the first place.

Dimension	selftune	Langfuse	LangSmith	OpenLIT
Layer	Skill-specific	LLM call	Agent trace	Infrastructure
Detects	Missed triggers, false negatives, skill conflicts	Token usage, latency	Chain failures	System metrics
Improves	Descriptions, body, and routing automatically	—	—	—
Setup	Zero deps, zero API keys	Self-host or cloud	Cloud required	Helm chart
Price	Free (MIT)	Freemium	Paid	Free
Unique	Self-improving skills + auto-rollback	Prompt management	Evaluations	Dashboards

Platforms

Claude Code (fully supported) — Hooks install automatically. selftune ingest claude backfills existing transcripts. This is the primary supported platform.

Codex (experimental) — selftune ingest wrap-codex -- <args> or selftune ingest codex. Adapter exists but is not actively tested.

OpenCode (experimental) — selftune ingest opencode. Adapter exists but is not actively tested.

OpenClaw (experimental) — selftune ingest openclaw + selftune cron setup for autonomous evolution. Adapter exists but is not actively tested.

Requires Bun or Node.js 18+. No extra API keys.

---

Architecture · Contributing · Security · Integration Guide · Sponsor

MIT licensed. Free forever. Primary support for Claude Code; experimental adapters for Codex, OpenCode, and OpenClaw.