Operate the ak CLI safely with ak:ak

Use ak:ak when the next concrete action is running an ak subcommand or interpreting its output. This Skill owns the safe operating model for the control-plane CLI itself — not the flag reference, which stays authoritative in ak <cmd> --help and the --json envelope.

Choose ak:ak for CLI operation

Use ak:ak when

• The next action is invoking an ak subcommand (init, kit, skills, plan, journal, doctor, recover, self-update, login, …).
• You need to disambiguate a read-only inspection from a mutating lifecycle command before it lands.
• You need to disambiguate project vs user/global scope, adapter, or delivery mode before a change hits somewhere unexpected.
• You need to interpret an ak <cmd> --json envelope.

Choose another Skill when

• Authoring or refining a Claude Skill — use ak:skill-creator.
• Writing or executing an implementation plan — use ak:plan or ak:cook.
• Writing a technical journal entry — use ak:journal.
• Choosing which installed Skill fits a task — use ak:agentkit (task router).
• Any kit-specific workflow already covered by its own Skill — use that Skill.

ak:agentkit decides which Skill runs. ak:ak runs the ak binary itself.

Safe operating protocol

1. Classify the requested operation and identify its project/user scope, Kit, runtime and delivery mode.
2. Inspect the installed binary's version and command help. Reuse that evidence within the session while the binary, version and target are unchanged; inspect again after an update or target change.
3. Use read-only status/validation before lifecycle changes. Inspect partial state before a retry; a retry within the existing authorized scope does not require repeated confirmation.
4. Continue additive or safely reconcilable changes inside existing user authorization. --yes and --no-interactive are appropriate for authorized scripted work when supported by that command. A prompt is not the only mutation boundary; some writers act directly.
5. Destructive overwrite, reset, restore or removal needs explicit scope authorization and the supported preview/snapshot safeguards. Preserve unknown and modified files. Never combine --force and --fresh.
6. Report the exact command, scope, result and unresolved evidence. Use --json for machine-readable output. --quiet overrides --verbose; do not rerun a mutation merely to obtain verbose logs.

Command families by task

• Bootstrap and setup — ak init, ak new, ak setup, ak onboard. All mutating; confirm intended kit and scope first. ak setup writes user config only. ak onboard runs setup, CLI login, then kit install.
• Kits — ak kit init|install|refresh|validate|uninstall|list-kits|repair-install-mode. list-kits and validate are read-only; the rest mutate.
• Skills — inventory (ak skills list|show|search|install|remove|graph) and per-skill environment (ak skill install|remove|repair|upgrade|verify).
• Agents, content, commands — mirror the skills shape: reads (list, show, search), writes (install, remove), and one domain-specific mutating action per group.
• Plans and journals — file-first plan and journal management. ak plan list|show|status|search|validate|resolve|parse are read-only. ak plan create|check|uncheck|add-phase|update|use|archive|close|reindex|migrate mutate. ak plan kanban is a diagnostic TUI. ak journal list|show|validate read; ak journal create writes.
• Diagnostics — ak doctor, ak activity, ak audit, ak sessions, ak analytics, ak backups, ak versions, ak changelog, ak diagnostics export. Mostly read-only; enable/disable/delete under analytics and content-search mutate.
• Shadow decision comparison — ak eval decision <request.json|-> runs an explicit shadow comparison. Treat it as mutating: enabled calls send data externally and may incur charges, even though it writes no local report. It requires user-scope semantic_decision consent, and project config can only restrict it. Never enable it from an ambient credential or as part of ordinary routing. Check status, fallback_reason, and provenance; the effective decision always remains the supplied legacy decision. See the ak eval decision reference.
• Workflow, triage, and UI experiments — ak eval workflow validates scenario, fix, or debug decision facts in the default off mode; --mode shadow also requires explicit workflow-controller consent and may incur charges. ak eval triage compares shadow finding triage with authoritative review decisions, and ak eval ui reports opt-in shadow UI regression signals, which in shadow mode need explicit ui-regression consent. Classify all three as mutating. Effective actions, review authority, and deterministic test outcomes stay unchanged. ak eval workflow-benchmark, ak eval triage-benchmark, and ak eval ui-benchmark evaluate local labeled evidence offline and are read-only.
• Test impact — ak test optimize --base <ref> --json plans without executing checks, but classify it as mutating: --run executes trusted repository commands and --output creates a new receipt. Semantic mode defaults to off; explicitly granted modes can send compact facts externally and incur charges, shadow keeps the baseline, and advisory only adds checks. ak test classify-e2e needs its own consumer grant, may incur charges, and never edits the class manifest. ak test benchmark is mutating because it executes a trusted regression corpus in isolated temporary workspaces; --semantic-replay stays offline.
• Secrets — ak secrets list, get, export, and recovery list are read-only. set, delete, rotate, import-env, approve, audit, grant, grants, revoke, trust, and recovery accept-rollback|add|init|remove are classified as mutating.
• Runtime orchestration — inspect installed ak orchestrate --help first. probe runs bounded version/help checks and writes an owned metadata cache; it does not prove authentication or invoke inference. prepare, advance, and accept persist resolved job, attempt, and artifact evidence. events, output, and diagnose inspect recorded evidence; plan-status and lifecycle status/resume may persist reclassification. External process supervision requires Darwin. Diagnostic bundles exclude private argv and environment.
• Recovery — ak recover, ak backups restore. Mutating and irreversible without a prior ak backups create.
• Watch and daemons — ak watch start|stop|status|dry-run, ak content schedule daemon, ak codex-agent-runtime serve, ak api start|stop|status, ak config start|stop|status.
• Config, auth, and MCP — ak config prefs resolve|set|unset|validate, top-level auth (ak login, ak logout, ak whoami, ak licenses), and ak mcp add|link|list|remove|show|verify. Auth commands are top-level, not under an ak auth parent.
• Self-update and migrations — ak self-update, ak migrate prefs|rollback. Run ak versions and check ak changelog before invoking.
• Background auto-update — ak update --schedule daily|weekly|off, --project/--no-project, and --ack are settings flags: mutating (they write auto_update: in ~/.agentkit/config.yaml), but they apply no update themselves. ak update --status is read-only. Never turn on a schedule or opt in a project without an explicit user request.

Source of truth

The generated command appendix carries a version stamp. If it lags behind ak --version, treat it as a starting hint and re-check flags with ak <cmd> --help when the binary, version, target, or command contract changes. ak self-update advances the binary independently of installed skill content, so version skew is normal after self-update and before the next ak update refresh.

Authoritative surfaces, in order:

1. ak <cmd> --help — always current for the running binary.
2. ak <cmd> --json output — versioned envelope, parseable.
3. The Skill's bundled command reference — starting index, may lag.

Anti-patterns

• Do not combine --force with --fresh on any lifecycle command.
• Do not run installer, refresh, migration, uninstall, or destructive smoke tests against real maintainer state. Set a temporary AgentKit home first.
• Do not invent flags not present in ak <cmd> --help. The Cobra metadata is authoritative.
• Do not treat a source-only capability as active in the installed binary. Confirm via ak versions or ak doctor.
• Do not infer adapter capability from another adapter.
• Do not report a mutating command's outcome without the resolved scope — say project vs global, adapter, and any conflict skipped.

Related Skills

• ak:agentkit — task router (which Skill runs).
• ak:skill-creator — author Claude Skills.
• ak:plan — implementation plan lifecycle.
• ak:journal — technical journal entries.

For effectiveness and local usage, see ak insights, ak eval and ak usage. Collection, evaluation, consent and contribution have different effects; inspect each command before invoking it.