ak skills kit apply

Resolve a personal kit and project every skill of its composition into the native skills roots, owned by personal:<name>.

Use ak skills kit apply to project a personal kit. The command resolves the kit, compares each composition with the running one (with the foundation base on a first apply) and projects the result. Review findings report changed scripts, modes, capabilities, exposure or license.

Usage

ak skills kit apply <name> [flags]

Options

Flag	Default	Description
`--dry-run`	`false`	Print the plan, its review findings and plan token; write nothing.
`--plan <token>`	Empty	Plan token from `--dry-run`. Required when the plan needs review; when given, it must equal the current token.
`--scope <scope>`	`project`	Lock and skills root scope: `project` or `global`.
`--runtime <list>`	The manifest's runtimes	`claude-code`, `codex`; repeatable. The running revision's runtimes are always included.
`--kits-dir <dir>`	`$AGENTKIT_KITS_DIR` or `./kits`	Foundation kits directory.

Shared flags are described in CLI conventions. A manifest runtime the command cannot project into is skipped with a warning; a manifest that names no runtime it can project into is refused unless --runtime is passed.

Requirements

The skill store must be on, after ak update --ssot or with AGENTKIT_SKILL_STORE=1, for dry runs too; with it off the command exits 2. The store gate follows --scope.

What it does

A clean plan applies without prompting. A plan with review findings applies only with --plan set to the token --dry-run shows. In one journaled transaction under the kit lifecycle lock the command writes the composed trees into the skill store under AGENTKIT_HOME, the projected files into each runtime's native skills root (mode 0644, never executable), and the scope's skill lock and receipts, owned by personal:<name>. Running sessions may see the new files as soon as the transaction commits.

Skills the kit no longer projects lose its reference; the previous revision is kept for ak skills kit rollback.
An alias owned by a legacy kit install, another owner or a file you created is refused and preserved.
After a rebase, an apply whose manifest still pins the older foundation version is refused with personal_kit.pin_behind until you update the version in personal-kit.yaml.
A decision whose base pin is missing or unreadable blocks the apply.

The command never rewrites the personal kit or the foundation kits, and never runs a script.

Output

The text output shows the kit with its status and required approval, each review finding, the new and previous revision (inputs digest and foundations), the plan token, and the transaction plan.

JSON uses kind=skills.kit.apply with these fields under data:

personalKit, status (clean | needs-review), requiredApproval, planToken,
findings[]
revision, previous: inputsDigest, foundations[], runtimes[],
                    packages[]: identity, alias, kind, foundation,
                                baseTreeDigest, overlayDigest,
                                compositionDigest, exposure, trust,
                                scriptsDeclared, resolutionDigest
plan: operation, scope, dryRun, applied, changed, planDigest, lockPath,
      lockGeneration, packages[], targets[], warnings[]

plan has the shape of the ak skills sync plan.

Exit behavior

Exit	Meaning
`0`	Success, or nothing to change.
`1`	Command failure, such as a path too long or a recovery that is required.
`2`	The skill store disabled, invalid flags or arguments, or a malformed manifest or proposal.
`4`	Another AgentKit operation holds the kit lifecycle lock.
`5`	Personal kit, foundation, version or skill not found.
`6`	Review required, stale plan token, rebase conflict, alias collision (including a legacy kit alias), or an unowned or modified path.
`7`	Revoked foundation, a link in a target path, or a digest mismatch.