3.2.0-beta.10). Features may change before the next stable release.Switch to stable →ak skills kit
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, else ./kits, else the cached installed build of the extended kit | 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-downgradereplays it with a warning and a review findingreview.foundation_downgradethat 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, planThe fields after offline are those of skills.kit.apply.
Progress
SkillX requests and the store work can take a while on a slow network. In text
mode a SkillX request still waiting after 10 seconds, and every retry, prints a
[~] line on stderr naming the request and how long it has waited. With
--verbose the command also prints each request with its size and time, and
its compose and apply steps. --json and --quiet print no progress.
Every network wait is bounded: each address connect gets 10 seconds (IPv6 and
IPv4 are raced, so a broken family does not stall the run), response headers
30 seconds, a body that sends nothing 30 seconds, and an attempt 2 minutes.
A request that keeps failing due to a network outage can return
source.offline after three attempts.
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. When SkillX no longer shows the linked kit to your credential, the error names the two causes: the kit was unpublished (restore it within 30 days with ak skills kit restore), or the credential belongs to another account. |
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. |
10 | Personal kits are not enabled for your account yet (SkillX answered kit.api_disabled). Local personal kits keep working; publish, sync and revisions work once SkillX enables them. |