Installing kits

A kit bundles skills and their supporting files for a coding assistant. This guide helps you install the kit into the right runtime and scope without overwriting unrelated work.

Before you start

Sign in and confirm that your account can install the kit:

ak whoami
ak licenses

An unauthenticated local state can still exit 0; read the command output rather than treating a successful exit as proof of authentication or entitlement.

Released kits come from the authenticated AgentKit registry by default. You do not need --remote. Local Kit sources are for development and CI, not the normal installation flow.

Predict lifecycle changes

Think of each command as a state transition. Updating one layer does not imply that the other layers changed.

The table describes ownership and state, not every flag. Use the linked CLI reference for the exact syntax supported by the active release.

Choose a runtime and scope

Released runtime installs use --target claude-code, --target codex, or --target cursor. Claude Code is the default when you omit the flag. Released registry packages are resolved for one runtime at a time, so run a separate install for each runtime you use. Native --target grok is a separate local-source spike, described below.

The default scope is the current project. Add --global when you want the kit in the runtime's user directory and available beyond one project. Together, target, scope, and delivery mode identify one install route:

Cursor and AGY use their own target surfaces, while portable is an export and does not create installed lifecycle state. The Grok rows apply only to its explicit local-source path. The previewed destination is the authority when an environment overrides a normal runtime root.

Project-scoped installs write runtime content in the current project and keep AgentKit lifecycle metadata there. Global installs write into the selected runtime's user scope. Review the destination shown in the install preview before confirming.

portable is export-only. --target portable without --out exits 1 before preview, confirmation, registry resolution, lifecycle preflight, or disk writes:

init: target "portable" is export-only and has no install mode; re-run with --out DIR to export a standalone build

--out implies build mode and preserves the remote source default; explicit --build-only --out remains valid but selects the local-development source default. Portable exports create no installed-lifecycle metadata.

agy is global-only. A remote AGY install resolves and caches the signed claude-code registry package, then projects Skills to ~/.gemini/config/skills/ and ~/.gemini/antigravity-cli/skills/, optional Agents to ~/.gemini/config/agents/, and its routing and ownership files. Unsupported parts warn and are skipped. AGY is not a registry runtime identity or a refresh lifecycle peer.

For Codex, native skills go to .agents/skills in a project or ~/.agents/skills at user scope; other Codex resources use the corresponding project or user .codex surfaces. Cursor uses the corresponding .cursor scope.

Project and global copies can coexist. Installing one does not remove the other: project commands or rules may shadow user entries, and hooks from both scopes may run. Remove an unwanted copy through the matching uninstall route.

Use the native Grok Build spike

Use an explicit local Kit source for development or CI:

ak kit init engineer --local --kits-dir ./kits --target grok
ak kit init engineer --local --kits-dir ./kits --target grok --global
ak kit refresh engineer --local --kits-dir ./kits --target grok

Remote Grok init and refresh fail closed because no signed Grok runtime package exists. Do not substitute a Claude Code, Codex, or Cursor package. Project installs use <project>/.grok; global installs use ${GROK_HOME:-~/.grok}. Lifecycle ownership stays in the separate .agentkit/adapters/grok/<kit> route shown above.

This native route is distinct from Grok's Claude-compat scanner reading .claude/settings.json. Native project Hooks remain inactive until you explicitly trust the project in Grok. Hook timeout, crash, and malformed output fail open; only an applicable PreToolUse denial blocks an action. For AgentKit dispatch, ak run <kit>/<skill> --target grok resolves AGENTKIT_GROK_BIN or grok, while Grok and the user retain ownership of model, authentication, trust, permissions, sandbox, and .grok/config.toml. See Grok CLI Hook errors only when you deliberately use Claude-compat scanning.

Choose Claude Code delivery

Claude Code supports two delivery modes:

• Native is the default. AgentKit merges its managed resources into the project or user Claude Code structure.
• Plugin is explicit. Add --switch-to-plugin at either scope.

# project plugin
ak kit install engineer --target claude-code --switch-to-plugin

# user plugin
ak kit install engineer --target claude-code --global --switch-to-plugin

Native Claude Code content goes to <project>/.claude or ~/.claude. The user plugin is installed as ak-<kit> under the Claude Code plugin root; for example, the default Engineer Kit path is ~/.claude/plugins/ak-engineer. Keep the same delivery and scope flags when you later refresh it. For uninstall, match the same route with --plugin-mode instead of --switch-to-plugin.

Follow the projection

AgentKit resolves the Kit package first, then projects the selected content into the native surfaces supported by the install route.

flowchart LR
  package["Resolved Kit package"] --> selection["Selected Skills and supporting content"]
  selection --> route["Target + scope + delivery"]
  route --> agents["Target-native agents"]
  route --> skills["Target-native skills"]
  route --> commands["Commands"]
  route --> hooks["Hooks"]
  route --> rules["Rules"]
  route --> sidecars["Lifecycle and ownership sidecars"]

A target may drop or narrow a surface it cannot support; the install report discloses that projection. The sidecars preserve route identity, selected Skills, owners, and fingerprints so later refresh, audit, and uninstall can reason about the files already present.

“Workflow” is a product concept, not a separately synchronized workflows/ directory in the current package. Workflow behavior is composed through the projected rules, Skills, agents, commands, and hooks. Do not use the absence of a workflows/ directory as evidence that projection failed.

Select skills

Without a selection flag, AgentKit installs every skill in the kit. Use one of these mutually exclusive choices when you want a smaller set:

# install only these skills
ak kit install engineer --target codex --skills ak-cook,ak-plan

# install everything except this skill
ak kit install engineer --target claude-code --exclude-skills ak-video

# choose interactively
ak kit install engineer --target claude-code --select-skills

--select-skills requires an interactive terminal. Use --skills or --exclude-skills in scripts. AgentKit installs the supporting references, scripts, and assets required by the selected skills.

Choose a release channel

Kit installation and refresh use the stable registry channel by default. To try a prerelease kit, opt into beta explicitly and keep the CLI on a compatible channel:

ak kit install engineer --target claude-code --channel beta

Do not mix channels as a troubleshooting shortcut. If a kit reports that it requires a newer ak, update the CLI on the same channel, then retry the kit operation.

Understand ownership and fingerprints

AgentKit records both the managed path and a fingerprint of the bytes it wrote. Later operations compare the current path and content with that evidence rather than adopting whatever happens to exist at the destination.

Symlinks, unsafe path transitions, and other ambiguous filesystem state also fail closed or remain preserved. Ownership evidence qualifies cleanup; it never means deleting an entire .claude, .codex, .grok, or user runtime directory.

Refresh an installed kit

Refresh re-emits the current Kit and removes stale generated or owned paths only when they still match AgentKit's ownership evidence. Modified, unsafe, linked, or other-kit-shared paths are preserved. Released targets use the remote registry by default and create a snapshot before destructive writes. The Grok Build spike instead requires the explicit --local --kits-dir source shown above:

ak kit refresh engineer --target codex
ak kit refresh engineer --global --switch-to-plugin

The refresh preview is a confirmation screen, not a dry run. In a script, JSON mode, or another non-interactive session, the prompt is skipped and the operation can proceed to writes. Use --yes for an intentional scripted refresh. Use the preview-only ak update flow from the update guide when you need a plan that cannot apply changes.

If the previous install selected only some skills, refresh reuses that selected set. Skills removed from the new release do not make the refresh fail, and new skills are not added to that subset automatically.

Review the preview before confirming. Do not add --no-backup, and do not use a broad --force reinstall as routine recovery. First resolve an incorrect target, scope, delivery mode, or ownership conflict.

Reconcile current and stale output

Refresh compares the new projection with the recorded projection for the same route:

The previous selected-Skill subset remains the selection for this route unless you explicitly change it. A Skill newly added to the package is therefore not silently added to a previously restricted install.

Read a .claude before/after example

The names below are illustrative; they show lifecycle classes without copying a mutable Kit inventory.

Before refresh:

.claude/
├── rules/current-rule.md          clean owned; old fingerprint
├── rules/retired-rule.md          clean owned; no longer projected
├── rules/shared-rule.md           clean; owned by Kit A and Kit B
├── skills/edited-skill/SKILL.md   owned; user-edited bytes
└── custom-note.md                 unknown custom file

After refreshing Kit A:

.claude/
├── rules/current-rule.md          rewritten; new fingerprint
├── rules/shared-rule.md           preserved; Kit B still owns it
├── skills/edited-skill/SKILL.md   preserved; modification reported
└── custom-note.md                 preserved; never adopted

retired-rule.md is removed only because it was still clean. The shared rule is removed only after every owner releases it. The edited Skill and custom file are not overwritten merely because their locations overlap the projected tree.

Audit and migrate safely

ak audit is read-only. It compares current content with recorded ownership fingerprints and reports drift without repairing, adopting, or deleting paths. Use that evidence to explain why a refresh preserved a file.

ak migrate is a separate planned mutation. Review the plan, keep the pre-apply snapshot, and use its migration rollback path when you need to reverse applied migration work. Migration does not broaden Kit ownership to unrelated runtime content.

Read Codex hook disclosures

A successful Codex install can report both Hooks dropped (unsupported on this target) and Hook matchers narrowed (some tool matches unsupported on this target). A full drop removes an unsupported group. A narrow keeps its handlers on the supported matcher subset and reports only the removed atoms.

In JSON output, inspect the optional hooksDropped, droppedHookSummaries, hookMatchersNarrowed, and narrowedHookSummaries fields. Engineer currently has one full drop and two shared narrows; Marketing has no full drop and three narrows. These are runtime capability limits, not install failures; reinstalling with --force does not restore unsupported matcher atoms.

Verify the result

After installation or refresh:

1. Confirm the command reports the expected target, scope, delivery mode, and selected-skill count.
2. Reopen the target runtime if it was already running.
3. Invoke one of the skills you installed. For example, use /ak:cook in Claude Code and $ak:cook in Codex.

If the runtime cannot find the skill, check the target, scope, and Claude Code delivery mode before reinstalling.

If files did not change

Use this decision order instead of deleting .claude or retrying with --force:

1. Command: did you update the binary, update project-owned content, or refresh the installed Kit route?
2. Versions and channel: do the CLI and resolved Kit versions match what you expected?
3. Route: does target, project/global scope, and native/plugin delivery match the original install?
4. Selection: was the missing file part of the recorded selected-Skill subset?
5. Projection: did the target report that a resource or hook matcher was dropped or narrowed?
6. Ownership: does audit show the path as modified, unknown, unsafe, linked, or shared?
7. Result: inspect preserved and skipped paths in the preview or summary, then choose recovery or a deliberate route-specific change.

See Updating AgentKit and Kits for choosing the correct update layer and preview flow. Use the generated references linked above for current flags rather than copying flags from an older command.

Remove a kit

Preview uninstall with the same scope and delivery mode as the install. The examples below select a Claude Code user plugin:

ak kit uninstall engineer --global --plugin-mode --dry-run
ak kit uninstall engineer --global --plugin-mode --yes

The dry run changes nothing and exits 3. This is expected preview behavior; apply only after reviewing the preserved and removed paths.

For a project plugin, replace --global with --project-dir .. For a native project install, use --project-dir . without --plugin-mode; for a native global install, use --global without --plugin-mode.

Uninstall removes matching AgentKit-owned files, preserves unknown or user-modified files, and snapshots before applying changes. Never remove an entire runtime configuration directory to uninstall one kit. If the operation prints a recovery snapshot, keep that ID until you have verified the runtime.

For native installs, cleanup then removes only empty ancestor directories owned by that installation. It stops at a shared-owner boundary or shared runtime root, and keeps directories containing user content or links. Unsafe traversal or a path replaced during cleanup is rejected rather than followed or removed.

See also

• Updating AgentKit and kits