skills/skills/autotune/SKILL.md

---
name: autotune
description: >
  Generate new skills or optimize existing ones (fewer tokens, fewer errors,
  persistent learnings), each proposal confirmed by single-select question.
  Trigger ONLY on an explicit request: /autotune, "autotune", "tune the
  skills"; never on your own initiative.
---

Autotune turns observed friction into durable skills. It runs on demand only,
it changes nothing without an explicit answer from the operator, and every
skill it writes or rewrites lands in the operator's skills repository.

## Objective

The shared objective of the self-improving skills (autotune, autoskill,
confidence): every skill, rule, or report the agent produces about its own
working is judged on three axes at once. A proposal that cannot name the axis
it moves is not an optimization, it is a preference.

- **Tokens** — fewer input and output tokens for the same result: read the range
  instead of the whole file, grep the saved log instead of re-running the
  command, route to an authoritative doc instead of duplicating it, report in
  lines instead of paragraphs.
- **Time** — fewer round trips and less waiting: independent calls in parallel,
  one command that answers the question instead of three that circle it, no
  polling for work the harness will report on its own.
- **Quality** — fewer errors and less rework: verification instead of
  assumption, and learnings that persist so the same mistake is not paid for
  twice.

- A change must improve at least one axis and damage none. Output that got
  cheaper but lost correctness is a regression, not an optimization.
- Quality is never the currency: validation, error handling, tests, and security
  steps are not what gets cut to save tokens or time.
- Measure, do not guess: name the observed friction — the re-read, the retry,
  the correction the operator had to give twice — and what it cost. A guessed
  percentage is not a measurement.
- The cheapest step is the one that does not run: drop work before optimizing
  it.
- Persist it or pay again: an optimization that lives only in this session is
  re-derived in the next one, so it belongs in a skill or a memory entry.

## Trigger discipline

- Run **only** when the operator asks: `/autotune`, "autotune", "tune the
  skills", or an equivalent instruction.
- The 60-minute reminder hook is a hint for the operator, not a trigger. When it
  fires, print the hint and continue the operator's actual request.
- Never propose, write, or edit a skill as a side effect of unrelated work.

## Step 1: collect evidence

Before asking anything, gather concrete friction from the current session and,
where readable, from the project's memory and agent instruction files:

- **Token waste**: repeated file re-reads, whole-file reads where a range was
  enough, long tool output pasted back, re-running a command instead of
  grepping a saved log, verbose report prose.
- **Errors**: rejected tool calls, permission prompts, retried commands,
  corrections the operator had to give twice.
- **Focus loss**: work that drifted beyond the request, unrequested tests or
  deploys, questions that stalled an autonomous run.
- **Lost learnings**: facts re-derived this session that a memory file or a
  skill should already have carried.

List each finding as one line: `symptom -> cost -> candidate fix`. Skip
anything that happened once and is not a pattern.

## Step 2: ask, do not decide

Use `AskUserQuestion` with `multiSelect: false` so every question renders as
radio buttons. Never assume an answer, never batch several decisions into one
option, and never write a file before the answers are in.

Ask in this order, at most four questions per call:

1. **Scope** - "What should autotune do this run?" Options: `Create a new
   skill`, `Optimize an existing skill`, `Both`, plus the ranked findings if
   more than one candidate exists.
2. **Target** - which finding becomes a skill, or which existing skill gets
   optimized. One option per candidate, each with its measured cost in the
   description.
3. **Shape** - for a new skill: `Standalone skill`, `Row in the shortcuts
   skill`, `Extend an existing skill`, `Memory entry instead of a skill`.
   For an optimization: `Tighten wording only`, `Change the trigger`, `Add
   rules`, `Split into two skills`, `Merge into another skill`.
4. **Placement** - `Operator skills repository (portable)` or
   `This project's skills directory (project-specific)`.

Present the drafted skill text (name, trigger phrasing, body outline) and ask
for a final `Write it` / `Revise it` / `Discard` confirmation before touching
disk. Rewrites of an existing skill additionally show a before/after diff of
the changed lines in that confirmation.

## Persistence

A skill that exists only under `.claude/skills` is lost on the next install, and
one that exists only in the repository is not live until the next restart — so
every skill is written to **both**, in this order:

1. **Locate the operator's skills repository.** Take the first hit: the
   `SKILLS_REPO` environment variable; the current repository, when it holds
   `skills-lock.json` and a `skills/` directory; `pkgmgr path skills`; a git
   checkout named `skills` under the usual roots
   (`~/Repositories/*/*/skills`, `~/git`, `~/src`, `~/Projects`) carrying
   `skills-lock.json`. If none matches, ask the operator for the path with a
   single-select question — never skip the repository and write only the live
   copies.
2. **Write the source of truth**: `skills/<name>/SKILL.md` in that repository
   (portable skills), or `skills/<name>/SKILL.md` in the current project
   (project-specific ones). This is the copy that gets committed.
3. **Mirror it live**, so it works without a reinstall: copy the skill's whole
   directory to `~/.claude/skills/<name>/` and `~/.agents/skills/<name>/`, and
   for a project-specific skill additionally to that project's
   `.claude/skills/<name>/` and `.agents/skills/<name>/`. Copy the directory,
   not just `SKILL.md`, so hooks and references come along.

Report all written paths. Deleting or renaming a skill follows the same list in
reverse — remove the mirrors too, or the old name keeps firing.

## Step 3: write

- Write the skill to every location the **Persistence** section lists.
- Frontmatter carries `name` and a `description` that states what the skill
  does **and** when to trigger it - the description is the only part loaded into
  every session, so it decides whether the skill ever fires.
- Body is thin and single-purpose: the smallest instruction that changes
  behaviour. Route to an authoritative doc instead of duplicating it.
- Optimizing an existing skill means the file gets shorter or sharper, not
  longer. Delete rules the agent already follows, merge duplicated ones, and
  cut every sentence that does not change an action. Route that compaction
  through the `essence` skill instead of trimming by hand: it runs a health
  pass for dead pointers and rules duplicated across skills before cutting
  anything, ranks by what loads in every session, and shows the diff before it
  writes. It asks for its own scope — answer with the skill being optimized.
- Report what changed in at most three lines, then refresh the reminder stamp
  so the next hint is an hour out: `date +%s > ~/.claude/.autotune-stamp`.

## Rules

- One skill per run unless the operator picked `Both`; a broad rewrite of the
  whole collection is not what autotune is for.
- Never write a skill for one-off work, for secrets, or for behaviour an
  existing skill already covers - propose extending that skill instead.
- The **Objective** section decides what counts as an improvement: at least
  one axis better, none damaged, and the claim named as observed friction rather
  than a guessed percentage.