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. When a --fresh plan stops with listed risks and a risk token, show the user each risk and its files, and rerun with --accept-risks <token> only after the user accepts that exact list. A token covers only the project, target, and Kit whose plan printed it; never reuse it elsewhere or save it for later runs. See ak kit init --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. Basic setup preserves stored telemetry consent and does not ask about it; change consent explicitly through ak setup, not as an onboarding prerequisite.
• 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 describe, 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. ak describe <cmd> --json returns a command's flags, exit codes, and agent contract offline.
• Improvement work — ak insights work list is read-only. work create writes a scoped plan in a registered project, and work defer|dismiss|awaiting-verification|verify persist local lifecycle state; classify them as mutating. verify compares recorded evidence and never runs a model or edits an artifact.
• 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. Credentials resolve from the process environment, then the AgentKit home .env, never a project .env. 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. Email OTP login needs an interactive terminal; for scripted or headless login, use the API-key route instead of piping a code.
• 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. A background project step reconciles only the tracked kits/ tree; an attended ak update <dir> --yes also refreshes every installed project runtime (--target a,b narrows them). 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 or ak describe <cmd> --json — always current for the running binary. See the command contract.
2. ak <cmd> --json output — read its declared framing from ak describe: versioned envelope, ndjson, protocol, or json-legacy; unspecified means unknown.
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.