AgentKit
DocsKitsCLI ReferenceDesktop App
BetaYou are reading docs for the beta channel (3.2.0-beta.10). Features may change before the next stable release.Switch to stable →

ak skills self-improve review

ak skills self-improve review approve

Preview a recorded improvement candidate, then apply it to your personal kit or record it as a proposal for an AgentKit skill.

Use ak skills self-improve review approve to act on a candidate that ak skills improve recorded. Without --yes it only previews. What --yes does depends on who owns the skill.

Usage

ak skills self-improve review approve <candidateId> [--yes] [--plan <token>] [--into <name>] [--kits-dir <dir>] [--dry-run] [flags]
ak skills self-improve review approve 3f2a91c0
ak skills self-improve review approve 3f2a91c0 --yes --plan sha256:... --json

Exactly one candidate reference is required: the candidate ID, or the short ID that review list prints.

Options

FlagDefaultDescription
--yesfalseApply or record instead of previewing.
--plan <token>EmptyPlan token of the reviewed preview. Required when the change needs review.
--into <name>The kit already overlaying the skill, else minePersonal kit to apply into.
--kits-dir <dir>$AGENTKIT_KITS_DIR or ./kitsFoundation kits directory.
--dry-runfalsePreview only and write nothing; the default without --yes.

Shared flags are described in CLI conventions.

A skill of your own personal kit

For a skill of your own personal kit (@local/), the command behaves exactly like ak skills evolution apply:

  • Without --yes, or with --dry-run, it previews the re-run evaluation, the diff, and the approval the apply still needs, and writes nothing.
  • With --yes, it applies the candidate: a rollback record first, a snapshot, and a journaled personal kit write. Applying needs the skill store on.
  • A change that needs review also needs --plan <token> from the preview you reviewed.
  • A regressed or blocked verdict refuses the apply. not_run and inconclusive are ordinary outcomes and need the plan token.

After a successful apply, the command records an approved decision in review.json. If that write fails, the apply stands and a warning says so. Undo the apply with ak skills evolution rollback.

An AgentKit skill

Every other skill, including an AgentKit skill, is proposal-only. The command never writes a kit file for it:

  • Without --yes, it says it would record a proposal, and points you to ak skills evolution show <id> to review the diff and propose it upstream as a pull request if you want it.
  • With --yes, it records a proposed decision in review.json, which silences the session-start line for the skill's current digest.

Output

For a personal kit skill, the text and JSON output are those of ak skills evolution apply: JSON uses kind=skills.evolution.apply.

For a proposal-only skill, the text output says would record proposed or recorded proposed for the skill, with a note. JSON uses kind=skills.self_improve.review.proposed with these fields under data:

skill, decision, recorded, evolution_candidate, note
decision: decision, digest, decided_at, candidate_id

recorded is false for a preview.

Exit behavior

ExitMeaning
0Success, including a preview.
1The candidate store, the personal kit, or the skill store could not be read or written, or a record failed verification (store.corrupt).
2Invalid flags or arguments, or an apply without the approval it needs (evolve.approval_required).
4Another AgentKit operation holds the kit lifecycle lock (evolve.store_busy).
5No recorded candidate matches, or the skill's base cannot be resolved (evolve.base_unresolved).
6The base moved since the candidate was recorded (evolve.base_changed), the evaluation refuses the apply (evolve.apply_refused), or the personal kit does not hold what the apply expects (evolve.apply_conflict).
7Redaction or the content gate could not be prepared (evolve.redaction_failed).