selftune

Category: Tools & Productivity | Uploader: selftune-dev | Downloads: 0 | Version: v1.0（Latest）
Self-improving skills toolkit that watches real agent sessions, detects missed triggers, grades execution quality, and evolves skill descriptions to match how users actually talk. Use when grading sessions, generating evals, evolving skill descriptions or routing tables, checking skill health, viewing the dashboard, ingesting sessions from other platforms, or running autonomous improvement loops. Make sure to use this skill whenever the user mentions skill improvement, skill performance, skill triggers, skill evolution, skill health, undertriggering, overtriggering, session grading, or wants to know how their skills are doing — even if they don't say "selftune" explicitly.
Changelog: Source: GitHub https://github.com/selftune-dev/selftune
Directory Structure

Current level: skill/
📁 agents/
- 📄 diagnosis-analyst.md 4.9 KB
- 📄 evolution-reviewer.md 4.4 KB
- 📄 integration-guide.md 4.6 KB
- 📄 pattern-analyst.md 4.3 KB
📁 assets/
- 📄 activation-rules-default.json 923 B
- 📄 multi-skill-settings.json 1.5 KB
- 📄 single-skill-settings.json 1.2 KB
📁 references/
- 📄 grading-methodology.md 6.2 KB
- 📄 interactive-config.md 1.9 KB
- 📄 invocation-taxonomy.md 6.9 KB
- 📄 logs.md 11.5 KB
- 📄 setup-patterns.md 2.4 KB
- 📄 version-history.md 1.5 KB
📁 Workflows/
- 📄 AlphaUpload.md 1.3 KB
- 📄 AutoActivation.md 5.5 KB
- 📄 Badge.md 3.3 KB
- 📄 Baseline.md 5.4 KB
- 📄 Composability.md 3.7 KB
- 📄 Contribute.md 3.7 KB
- 📄 Cron.md 6.8 KB
- 📄 Dashboard.md 6.2 KB
- 📄 Doctor.md 8.2 KB
- 📄 Evals.md 10.4 KB
- 📄 EvolutionMemory.md 5.2 KB
- 📄 Evolve.md 15.8 KB
- 📄 EvolveBody.md 8.0 KB
- 📄 Grade.md 4.9 KB
- 📄 ImportSkillsBench.md 3.2 KB
- 📄 Ingest.md 9.1 KB
- 📄 Initialize.md 15.7 KB
- 📄 Orchestrate.md 8.4 KB
- 📄 Replay.md 3.2 KB
- 📄 Rollback.md 4.2 KB
- 📄 Schedule.md 3.1 KB
- 📄 Sync.md 3.6 KB
- 📄 Telemetry.md 1.7 KB
- 📄 UnitTest.md 5.0 KB
- 📄 Watch.md 5.0 KB
- 📄 Workflows.md 4.3 KB
📄 settings_snippet.json 1.6 KB
📄 SKILL.md 20.3 KB
SKILL.md

---
name: selftune
description: >
  Self-improving skills toolkit that watches real agent sessions, detects missed
  triggers, grades execution quality, and evolves skill descriptions to match how
  users actually talk. Use when grading sessions, generating evals, evolving skill
  descriptions or routing tables, checking skill health, viewing the dashboard,
  ingesting sessions from other platforms, or running autonomous improvement loops.
  Make sure to use this skill whenever the user mentions skill improvement, skill
  performance, skill triggers, skill evolution, skill health, undertriggering,
  overtriggering, session grading, or wants to know how their skills are doing —
  even if they don't say "selftune" explicitly.
metadata:
  author: selftune-dev
  version: 0.2.10
  category: developer-tools
---

# selftune

Observe real agent sessions, detect missed triggers, grade execution quality,
and evolve skill descriptions toward the language real users actually use.

**You are the operator.** The user installed this skill so YOU can manage their
skill health autonomously. They will say things like "set up selftune",
"improve my skills", or "how are my skills doing?" — and you route to the
correct workflow below. The user does not run CLI commands directly; you do.

## Why this matters

Skills are only useful when they trigger at the right time with the right
instructions. But user language drifts — the phrases people use to ask for help
rarely match the trigger keywords a skill author imagined. selftune closes this
gap by observing real sessions, finding where skills fail to activate or
execute poorly, and rewriting descriptions to match actual usage patterns. The
result: skills that get better over time without manual tuning.

## Communicating with the user

Users range from experienced developers who'll say "evolve the pptx description
using the latest eval set" to non-technical users who'll say "make my skills
better". Pay attention to context cues:

- If they use terms like "eval set", "routing table", "JSONL" — match their precision
- If they say "improve my skills" or "how's it going" — explain what you're doing in plain language, summarize results, and suggest next steps
- When in doubt, briefly explain what a command does before running it

## Bootstrap

If `~/.selftune/config.json` does not exist, read `Workflows/Initialize.md`
first. The CLI must be installed (`selftune` on PATH) before other commands
will work. Do not proceed with other commands until initialization is complete.

## Command Execution Policy

```bash
selftune <command> [options]
```

Commands vary in output format. `selftune orchestrate`, `selftune watch`, and
`selftune evolve --dry-run` emit structured JSON on stdout. `selftune status`,
`selftune last`, and `selftune doctor` print human-readable text or structured
JSON depending on the command. For alpha/bootstrap and health remediation, prefer
machine-readable `guidance.next_command` or top-level `next_command` when present
instead of inferring the next step from prose. `selftune dashboard` starts a
local SPA server — it does not emit data.

## Quick Reference

```bash
# Ingest group
selftune ingest claude   [--since DATE] [--dry-run] [--force] [--verbose]
selftune ingest codex                                                          # (experimental)
selftune ingest opencode                                                       # (experimental)
selftune ingest openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
selftune ingest wrap-codex -- <codex args>                                     # (experimental)

# Grade group
selftune grade auto      --skill <name> [--expectations "..."] [--agent <name>]
selftune grade baseline  --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]

# Evolve group
selftune evolve          --skill <name> --skill-path <path> [--dry-run]
selftune evolve body     --skill <name> --skill-path <path> --target <body|routing> [--dry-run]
selftune evolve rollback --skill <name> --skill-path <path> [--proposal-id <id>]

# Eval group
selftune eval generate      --skill <name> [--list-skills] [--stats] [--max N] [--seed N] [--output PATH]
selftune eval unit-test      --skill <name> --tests <path> [--run-agent] [--generate]
selftune eval import         --dir <path> --skill <name> --output <path> [--match-strategy exact|fuzzy]
selftune eval composability  --skill <name> [--window N] [--telemetry-log <path>]

# Other commands
selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
selftune status
selftune last
selftune doctor
selftune dashboard [--port <port>] [--no-open]
selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
selftune cron setup [--dry-run]                         # auto-detect platform (cron/launchd/systemd)
selftune cron setup --platform openclaw [--dry-run] [--tz <timezone>]  # OpenClaw-specific
selftune cron list
selftune cron remove [--dry-run]
selftune telemetry [status|enable|disable]
selftune export    [TABLE...] [--output/-o DIR] [--since DATE]

# Alpha enrollment (device-code flow — browser opens automatically)
selftune init --alpha --alpha-email <email>
selftune alpha upload [--dry-run]
selftune status                                                        # shows cloud link state + upload readiness
```

## Workflow Routing

| Trigger keywords                                                                                                                        | Workflow          | File                                  |
| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------- |
| grade, score, evaluate, assess session, auto-grade                                                                                      | Grade             | Workflows/Grade.md                    |
| evals, eval set, undertriggering, skill stats, eval generate                                                                            | Evals             | Workflows/Evals.md                    |
| evolve, improve, optimize skills, make skills better, triggers, catch more queries                                                      | Evolve            | Workflows/Evolve.md                   |
| evolve body, evolve routing, full body evolution, rewrite skill, teacher student                                                        | EvolveBody        | Workflows/EvolveBody.md               |
| evolve rollback, undo, restore, revert evolution, go back, undo last change                                                             | Rollback          | Workflows/Rollback.md                 |
| watch, monitor, regression, post-deploy, keep an eye on                                                                                 | Watch             | Workflows/Watch.md                    |
| doctor, health, hooks, broken, diagnose, not working, something wrong                                                                   | Doctor            | Workflows/Doctor.md                   |
| ingest, import, codex logs, opencode, openclaw, wrap codex                                                                              | Ingest            | Workflows/Ingest.md                   |
| replay, backfill, claude transcripts, historical sessions                                                                               | Replay            | Workflows/Replay.md                   |
| contribute, share, community, export data, anonymized, give back                                                                        | Contribute        | Workflows/Contribute.md               |
| init, setup, set up, bootstrap, first time, install, configure selftune, alpha, enroll, alpha enrollment, cloud link, upload credential | Initialize        | Workflows/Initialize.md               |
| cron, schedule, automate evolution, run automatically                                                                                   | Cron              | Workflows/Cron.md                     |
| auto-activate, suggestions, activation rules, nag, why suggest                                                                          | AutoActivation    | Workflows/AutoActivation.md           |
| dashboard, visual, open dashboard, show dashboard, serve dashboard, live dashboard                                                      | Dashboard         | Workflows/Dashboard.md                |
| evolution memory, session continuity, what happened last                                                                                | EvolutionMemory   | Workflows/EvolutionMemory.md          |
| grade baseline, baseline lift, adds value, skill value, no-skill comparison                                                             | Baseline          | Workflows/Baseline.md                 |
| eval unit-test, skill test, test skill, generate tests, run tests                                                                       | UnitTest          | Workflows/UnitTest.md                 |
| eval composability, co-occurrence, skill conflicts, skills together                                                                     | Composability     | Workflows/Composability.md            |
| eval import, skillsbench, external evals, benchmark tasks                                                                               | ImportSkillsBench | Workflows/ImportSkillsBench.md        |
| telemetry, analytics, disable analytics, opt out, tracking, privacy                                                                     | Telemetry         | Workflows/Telemetry.md                |
| orchestrate, autonomous, full loop, improve all skills, run selftune loop                                                               | Orchestrate       | Workflows/Orchestrate.md              |
| sync, refresh, source truth, rescan sessions                                                                                            | Sync              | Workflows/Sync.md                     |
| badge, readme badge, skill badge, health badge                                                                                          | Badge             | Workflows/Badge.md                    |
| workflows, discover workflows, list workflows, multi-skill workflows                                                                    | Workflows         | Workflows/Workflows.md                |
| alpha upload, upload data, send alpha data, manual upload, dry run upload                                                               | AlphaUpload       | Workflows/AlphaUpload.md              |
| export, dump, jsonl, export sqlite, debug export                                                                                        | Export            | _(direct command — no workflow file)_ |
| status, health summary, skill health, how are skills, skills doing, run selftune                                                        | Status            | _(direct command — no workflow file)_ |
| last, last session, recent session, what happened, what changed                                                                         | Last              | _(direct command — no workflow file)_ |

Workflows Grade, Evolve, Watch, and Ingest also run autonomously via `selftune orchestrate`.

## Interactive Configuration

Before running mutating workflows (evolve, evolve-body, evals, baseline), consult
`references/interactive-config.md` for the pre-flight configuration pattern, model
tier reference, and quick-path rules.

## The Feedback Loop

The core idea: observe how users actually talk, find where skills miss, propose
better descriptions, validate them, and deploy — with automatic rollback if things
get worse. Every step produces evidence so you can explain _why_ a change was made.

```text
Observe --> Detect --> Diagnose --> Propose --> Validate --> Audit --> Deploy --> Watch --> Rollback
   |                                                                    |
   +--------------------------------------------------------------------+
```

1. **Observe** — Hooks capture every session (queries, triggers, metrics)
2. **Detect** — `selftune eval generate` extracts missed-trigger patterns
3. **Diagnose** — `selftune grade` evaluates session quality with evidence
4. **Propose** — `selftune evolve` generates description improvements
5. **Validate** — Evolution is tested against the eval set before deploying
6. **Audit** — Persist proposal, evidence, and decision metadata for traceability
7. **Deploy** — Updated description replaces the original (backup kept)
8. **Watch** — `selftune watch` monitors for regressions post-deploy
9. **Rollback** — `selftune evolve rollback` restores previous version if needed

## Specialized Agents

selftune bundles focused agents in `agents/`. When you need deeper analysis,
read the relevant agent file and follow its instructions — either inline or
by spawning a subagent with those instructions as its prompt.

On Claude Code, `selftune init` also syncs compatibility copies into
`~/.claude/agents/` so native `--agent <name>` calls keep matching these
bundled definitions.

Treat these as worker-style subagents:

- pass the required inputs from the parent agent
- expect a structured report back
- do not have them question the user directly unless you explicitly want that

| Trigger keywords                                           | Agent file                     | When to use                                                                                                |
| ---------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| diagnose, root cause, why failing, debug performance       | `agents/diagnosis-analyst.md`  | When one skill has recurring low grades, regressions, or unclear failures after basic doctor/status review |
| patterns, conflicts, cross-skill, overlap, optimize skills | `agents/pattern-analyst.md`    | When multiple skills may overlap, misroute, or interfere, especially after composability flags conflict    |
| review evolution, check proposal, safe to deploy           | `agents/evolution-reviewer.md` | Before deploying a dry-run or pending proposal, especially for high-stakes skills or marginal improvements |
| set up selftune, integrate, configure project              | `agents/integration-guide.md`  | For complex setup and verification work in monorepos, multi-skill repos, or mixed-platform environments    |

## Examples

### Scenario 1: First-time setup

User says: "Set up selftune" or "Install selftune"

Actions:

1. Read `Workflows/Initialize.md`
2. Run `selftune init` to bootstrap config (hooks are installed automatically)
3. Run `selftune doctor` to verify

Result: Config at `~/.selftune/config.json`, hooks active, ready for session capture.

### Scenario 2: Improve a skill

User says: "Make the pptx skill catch more queries" or "Evolve the Research skill"

Actions:

1. `selftune eval generate --skill pptx` to find missed triggers
2. `selftune evolve --skill pptx --skill-path <path>` to propose changes
3. `selftune watch --skill pptx --skill-path <path>` to monitor post-deploy

Result: Skill description updated to match real user language, with rollback available.

### Scenario 3: Check skill health

User says: "How are my skills doing?" or "Run selftune"

Actions:

1. `selftune status` for overall health summary
2. `selftune last` for most recent session insight
3. `selftune doctor` if issues detected

Result: Pass rates, trend data, and actionable recommendations.

### Scenario 4: Autonomous operation

User says: "Set up cron jobs" or "Run selftune automatically"

Actions:

1. `selftune cron setup` to install OS-level scheduling
2. Orchestrate loop runs: ingest → grade → evolve → watch

Result: Skills improve continuously without manual intervention.

## Troubleshooting

### CLI not found

Error: `command not found: selftune`

Cause: CLI not installed or not on PATH.

Solution:

1. Run `npm install -g selftune` or check `bin/selftune.cjs` exists
2. Verify with `which selftune`
3. If using bun: `bun link` in the repo root

### No sessions to grade

Error: `selftune grade` returns empty results.

Cause: Hooks not capturing sessions, or no sessions since last ingest.

Solution:

1. Run `selftune doctor` to verify hook installation
2. Run `selftune ingest claude --force` to re-ingest
3. Check `~/.claude/` for telemetry JSONL files

### Evolution proposes no changes

Cause: Eval set too small or skill already well-tuned.

Solution:

1. Run `selftune eval generate --skill <name> --max 50` for a larger eval set
2. Check `selftune status` — if pass rate is >90%, evolution may not be needed
3. Try `selftune evolve body` for deeper structural changes

### Dashboard won't serve

Error: Port already in use or blank page.

Solution:

1. Try a different port: `selftune dashboard --port 3142`
2. Check if another process holds the port: `lsof -i :3141`
3. Use `--no-open` to start the server without opening a browser

## Negative Examples

These should NOT trigger selftune — note that several are near-misses that
share keywords but need different solutions:

- "Fix this React hydration bug" — general debugging, not skill improvement
- "Create a PowerPoint about Q3 results" — this is pptx skill, not selftune
- "Run my unit tests" — project tests, not skill eval tests (even though selftune has "eval unit-test", this is about _project_ tests)
- "How do I use the Research skill?" — skill _usage_, not skill _improvement_ (route to the Research skill itself)
- "Generate a report from this data" — content generation, not skill evolution
- "My build is failing" — project issue, not selftune health issue (even though "failing" overlaps with skill diagnostics language)
- "Evaluate this code for security issues" — "evaluate" here means code review, not session grading
- "Improve this function's performance" — code optimization, not skill optimization (even though "improve" and "performance" are selftune keywords)

The key distinction: selftune is about improving _skills themselves_ (their
descriptions, triggers, and execution quality). If the user is trying to
accomplish a task _using_ a skill, route to that skill instead.

## Resource Index

| Resource                            | Purpose                                             | When to read                                    |
| ----------------------------------- | --------------------------------------------------- | ----------------------------------------------- |
| `SKILL.md`                          | This file — routing, triggers, quick reference      | Always loaded                                   |
| `Workflows/*.md`                    | Step-by-step instructions for each workflow         | When routing to a workflow                      |
| `agents/diagnosis-analyst.md`       | Deep-dive skill failure analysis                    | Spawn when doctor/grades show persistent issues |
| `agents/pattern-analyst.md`         | Cross-skill conflict detection                      | Spawn when composability flags conflicts        |
| `agents/evolution-reviewer.md`      | Safety gate for evolution proposals                 | Spawn before deploying high-stakes evolutions   |
| `agents/integration-guide.md`       | Guided setup for complex projects                   | Spawn for monorepos, multi-skill setups         |
| `references/logs.md`                | Log file formats (telemetry, usage, queries, audit) | When parsing or debugging log files             |
| `references/grading-methodology.md` | 3-tier grading model, evidence standards            | When grading sessions or interpreting grades    |
| `references/invocation-taxonomy.md` | 4 invocation types, coverage analysis               | When analyzing trigger coverage                 |
| `references/interactive-config.md`  | Pre-flight config pattern, model tiers              | Before running mutating workflows               |
| `references/setup-patterns.md`      | Platform-specific setup patterns                    | During complex setup scenarios                  |
| `settings_snippet.json`             | Claude Code hook configuration template             | During initialization                           |
| `assets/*.json`                     | Config templates (activation rules, settings)       | During initialization                           |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
selftune

Directory Structure

SKILL.md

Report

Notice
