ak skills kit sync

Project exactly one pinned SkillX revision of a personal kit, byte-identical on every machine, never following a newer one.

Use ak skills kit sync --locked to project the SkillX revision a personal kit's link records (the last publish or sync), or the one --kit, --revision and --digest name. The revision document must hash to the pinned digest, and every skill is rebuilt from its pinned base and overlay and checked against its composition digest, so the same revision projects byte-identical trees on every machine. A newer revision is never followed.

Usage

ak skills kit sync <name> --locked [--kit @<handle>/<name> --revision <id> --digest sha256:<hex>] [flags]

--locked is required; without it the command exits 2.

Options

Flag	Default	Description
`--locked`	`false`	Required. Project only the exact pinned revision.
`--kit @<handle>/<name>`	The linked one	SkillX personal kit.
`--revision <id>`	The linked one	SkillX revision id to project.
`--digest sha256:<hex>`	The linked one	Revision digest the document must hash to.
`--allow-downgrade`	`false`	Replay a revision that pins a foundation older than the running one; needs review.
`--plan <token>`	Empty	Plan token from `--dry-run`; required when the plan needs review.
`--scope <scope>`	`project`	Lock and skills root scope: `project` or `global`.
`--runtime <list>`	The revision'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.
`--dry-run`	`false`	Print the plan, its review findings and plan token; write nothing.

Shared flags are described in CLI conventions. A personal kit without a SkillX link needs all three of --kit, --revision and --digest.

Requirements

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

What it does

The command reads the lock and revision document of the exact revision with the configured SkillX API key, and its bases from the foundation kits directory or, when it lacks them, from SkillX releases (verified, staged in a temporary directory that is removed). Then, like ak skills kit apply, in one journaled transaction under the kit lifecycle lock it writes the composed trees into the skill store, the projected files into each runtime's native skills root (mode 0644, never executable), the scope's skill lock and receipts, owned by personal:<name>, and AGENTKIT_HOME/state/personal-kits/<name>/skillx.json.

Review findings and plan tokens work as in ak skills kit apply.
When SkillX is offline and the scope already runs the pinned revision, the sync keeps it with an offline warning and exits 0; otherwise nothing changes.
A revision that pins a foundation older than the running one is refused with personal_kit.pin_behind. --allow-downgrade replays it with a warning and a review finding review.foundation_downgrade that the plan token approves.

The command never uploads, never follows a newer revision, never rewrites the personal kit, and never runs a script.

Output

The text output starts with the SkillX kit, revision id and digest. Offline with the pinned revision already running it prints unchanged; otherwise it continues with the ak skills kit apply output.

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

skillx: kit, revisionId, revisionDigest
offline
personalKit, status, requiredApproval, planToken, findings[],
revision, previous, plan

The fields after offline are those of skills.kit.apply.

Exit behavior

Exit	Meaning
`0`	Synced, nothing to change, or SkillX offline while the scope already runs the pinned revision.
`1`	Command failure: SkillX offline, the API key missing, scoped or expired, or a recovery that is required.
`2`	SkillX, the overlay flag or the skill store disabled, `--locked` missing, or an invalid pin, flag or argument.
`4`	Another AgentKit operation holds the kit lifecycle lock.
`5`	SkillX kit, revision, foundation, version or skill not found.
`6`	Review required, stale plan token, a foundation downgrade without `--allow-downgrade`, alias collision, or an unowned or modified path.
`7`	The revision document does not match its pin, carries an unsafe path or key, a revoked foundation, or a link in a target path.