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, --target cursor, --target dsh, --target grok, --target pi, or --target omp. 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. Pi projection and Oh My Pi dispatch are separate: Pi uses ak kit init ... --target pi for installable Kit content, while Oh My Pi can also be selected by ak run --target omp for Skill dispatch.

Every remote Kit operation below passes --channel <channel>. Replace <channel> with the release channel selected in the docs header. Omitting the flag on ak kit init and ak kit refresh uses the channel recorded in the existing destination's install receipt, then kit.channel, then stable. stable can return version_not_available when the selected runtime package exists only on another channel. ak kit install still resolves stable when the flag is omitted.

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. A project install, refresh, or uninstall whose route for any runtime resolves to the user-level install, such as one run from your home directory, is refused with exit 6 before any change; use --global there. Together, target, scope, and delivery mode identify one install route:

Cursor, Grok, and AGY use their own target surfaces, while portable is an export and does not create installed lifecycle state. 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 go to ~/.gemini/config/agents/<name>/agent.md, receive subagent: true, and omit incompatible tool-allowlist frontmatter. Routing and ownership files are projected alongside them. 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, described under Use native Codex below. 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 native Codex

A Codex emit resolves exactly one of three scopes:

Install, refresh, and uninstall merge or remove only AgentKit-owned entries in config.toml and hooks.json, so your own settings and other Kits' entries stay in place. A project install, refresh, or uninstall never writes ~/.codex; project uninstall removes only AgentKit entries from <project>/.codex/config.toml and hooks.json. Running a project install from your home directory, where the project .codex would be the user Codex home, is refused with exit 6 before any change; use --global there.

Uninstall also removes this Kit's managed rules block from AGENTS.md in the Codex runtime directory and keeps your own text and other Kits' blocks. A project uninstall also removes this Kit's entry from <project>/.agents/plugins/marketplace.json and keeps the other entries. The repository AGENTS.md is never changed. Codex does not read AGENTS.md from the project .codex directory, so a project install warns that rules written there are preserved but not active.

Codex loads <project>/.codex only for a trusted project. After a project install, AgentKit prints the runtime directory, the hooks.json path, and the project's trust state recorded in your user Codex configuration: trusted, untrusted, not-recorded, or unknown. JSON output reports the same fields under codexRuntime. AgentKit only reads the trust state and never writes it. To activate the project runtime, start Codex in the project and accept its trust prompt.

Older releases nested a project install under <project>/<kit>/, where Codex never found it. The next project ak kit init or ak kit refresh migrates that layout without a prompt:

1. It snapshots <project>/<kit>/ first.
2. It writes the project layout above.
3. It removes only legacy files whose hashes still match the legacy install manifest. Unknown, edited, and linked files stay in place, and without a legacy install manifest nothing is removed.
4. It prints a warning on stderr with the snapshot ID, its data directory, and any files it kept. JSON output reports the same outcome under codexRuntime.legacyMigration.

An interrupted migration is detected again and finishes on the next run.

Use native Grok Build

Use the signed registry package for normal installs:

ak kit init engineer --target grok --channel <channel>
ak kit init engineer --target grok --global --channel <channel>
ak kit refresh engineer --target grok --channel <channel>

Project installs use <project>/.grok; global installs use ${GROK_HOME:-~/.grok}. Lifecycle ownership stays in the separate .agentkit/adapters/grok/<kit> route shown above. Use an explicit local source only for development or CI, for example ak kit init engineer --local --kits-dir ./kits --target grok.

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.

Use native Pi

Install one Kit into a project-local Pi projection or the active Pi coding-agent profile:

ak kit init engineer --target pi --channel <channel>
ak kit init engineer --target pi --global --channel <channel>

Project installs write .pi/skills/ak-<slug>/SKILL.md, remapped Agents below .pi/agents/, owned rules below .pi/rules/, and first-party extensions under .pi/extensions/. Global installs resolve the active profile from PI_CODING_AGENT_DIR or ~/.pi/agent and write skills/, agents/, rules/, and extensions/ directly below that profile. A fresh global install refuses an occupied profile by default. If you have reviewed the listed paths and intend to overwrite them, re-run with explicit --force.

When the trusted project also contains the same ak-<slug> under .agents/skills/, AgentKit emits a warning without deleting either copy. A project Pi install under .pi/skills/ takes precedence; for a global Pi install, the trusted project's .agents/skills/ copy takes precedence over the profile copy.

Pi and Codex installed globally

A global Codex install writes Skills to ~/.agents/skills, which Pi also reads. Pi loads its profile skills/ first, so when the same Kit is installed globally for both Pi and Codex, the ~/.agents/skills copy never wins and would only make Pi report it under [Skill conflicts] at every startup.

To prevent that, a global Pi or Codex install or refresh, and every ak kit uninstall, reconciles the skills list in the Pi profile settings.json. For each ak-* Skill present in both ~/.agents/skills and the Pi profile skills/, AgentKit adds a !<absolute path> exclusion for the ~/.agents/skills copy, and it removes exclusions that no longer apply:

• AgentKit edits only the skills key of ~/.pi/agent/settings.json, or $PI_CODING_AGENT_DIR/settings.json when that variable is set, and only the entries it added. Your own entries and every other key are kept.
• The record of AgentKit-added entries lives in $AGENTKIT_HOME/pi-agents-skill-exclusions.json.
• A symlinked or unreadable settings.json, or one whose content AgentKit cannot safely edit, is left unchanged with a warning.
• While both copies exist, an AgentKit entry you remove is added back on the next global install or refresh.

If an older install still shows ak:-named Skills under ~/.agents/skills, run ak update --global to refresh them.

Pi is a spike Kit projection in this release. AgentKit does not provide ak run --target pi, does not wrap Pi's agent loop, and does not write .pi/commands/. Use Pi's own Skill discovery for installed .pi/skills/* content, and use ak run --target omp only when you intentionally dispatch through Oh My Pi instead.

For optional web access, code feedback, delegation, and other additions, see Recommended Pi extensions.

Use native Oh My Pi

Install one Kit into the current project or the OMP user scope:

ak kit init engineer --target omp --channel <channel>
ak kit init engineer --target omp --global --channel <channel>

Project installs write portable Skills to .omp/skills/ak-<slug>/SKILL.md; each projected file uses top-level name: ak-<slug>. Agents go to .omp/agents/<name>.md, and rules go to .omp/rules/<name>.md. Body aliases such as /ak:cook and $ak:cook remain unchanged. Kit instructions are merged into the project AGENTS.md between <!-- AGENTKIT-OMP:START:<kit> --> and <!-- AGENTKIT-OMP:END:<kit> -->; AgentKit preserves text outside that Kit's managed block. Unsupported surfaces are retained as inactive content under .agentkit/adapters/omp/<kit>/sidecars/.

For --global, the OMP root resolves from AGENTKIT_OMP_HOME, then OMP_HOME, then PI_CODING_AGENT_DIR, and finally ~/.omp/agent. Skills, Agents, rules, and AGENTS.md use the corresponding paths below that root. Review the preview when you override the root so the selected destination is explicit.

Trusted project OMP also discovers project .agents/skills. For a canonical collision such as ak:advise and ak-advise, project .omp/skills shadows the project .agents/skills copy after a project OMP install. When a global OMP install is used from that trusted project, project .agents/skills shadows the OMP profile copy. The install warns and continues without skipping OMP emission, deleting or rewriting either Skill, changing .agents or OMP settings, requiring --force, or returning exit 6.

Use ak run <kit>/<skill> --target omp when you want to dispatch one local Skill non-interactively through OMP. That command is a separate execution route; it does not replace the project or global install above.

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 --channel <channel>

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

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 --channel <channel>

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

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

--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 still uses the stable registry channel when --channel is omitted. ak kit init, ak kit refresh, and ak update resolve an explicit --channel first, then the channel recorded in an existing destination's install receipt, then kit.channel, then stable. An explicit --channel applies to that request only and is not saved, so set kit.channel if you want a lasting 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 normally fail closed or remain preserved. Codex has two distinct bounded link exceptions:

• A hooks directory leaf may point exactly to the resolved user's canonical ~/.codex/hooks, through a POSIX symlink or a Windows directory junction. AgentKit uses that canonical identity for the complete Hook lifecycle; other Hooks-directory targets still fail closed.
• The final config.toml leaf may be a symlink to a regular file. Managed writes go through to that target; if apply fails, rollback restores the target's previous bytes and retains the link. Nonregular targets are refused.

Linked parents remain refused in both cases; these exceptions do not permit arbitrary linked paths. 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 from a local development source 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.

When one target must hold only kit output again, use ak kit init <kit> --fresh --target <runtime>. It previews the exact files it removes, asks once, takes and verifies a recovery snapshot, emits the kit, and then sweeps leftovers inside the kit's own lifecycle root. Shared runtime roots change only through the kit's recorded files. See Reset one target with --fresh.

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 Hook groups not projected 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.

For global Codex Hooks, a wrapper-managed Codex home may alias only its final hooks leaf to canonical ~/.codex/hooks, using a POSIX symlink or a Windows directory junction. Do not generalize this to a linked Codex home or arbitrary Hook target; those remain refused.

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

Runtime capability map

DeepSeek Harness is a signed registry target. Use --target dsh; project Skills go under .dsh/skills, user Skills under ${DSH_HOME:-~/.dsh}/skills. Install scope, dispatch and live verification are separate capabilities. See the runtime matrix.

hooksDeferred is a subset of hooksDropped: the harness bridge defers that subscription, which does not mean the runtime cannot express it. Read the summary to distinguish deferred from unsupported groups.