rpk ai skill sync
Install the approved skills named in this repository’s manifest and in your own skill file into the folders Claude Code, Codex and OpenCode read. sync writes to each of them that is installed (its command is on PATH or its config folder exists) and skips the rest.
The repository manifest is .redpanda/skills.yaml at the root of the repository you run sync in. Commit it, so everyone working in the repository gets the same skills. Its skills go in the repository’s folders:
| Value | Description |
|---|---|
|
|
|
|
|
Your own skill file is skills.yaml in rpk ai’s state folder (~/.rpai`
for production). Its skills apply in every repository and go in your own
folders:
| Value | Description |
|---|---|
|
|
|
|
|
|
Both files have the same form. An entry follows a channel or pins a version; an entry with neither follows live, the newest approved version:
skills:
- name: pdf-forms
- name: release-notes
channel: draft
- name: sql-style
version: 3
The draft channel takes your newest draft, even when a newer version has been approved since, and takes live when you have no draft.
sync prints what it changed for each coding agent and whether running sessions see the change or need a restart.
sync owns the folders it installs: it replaces one when its version changes and deletes it when its skill leaves the manifest, so change a skill by publishing a new version, not by editing its synced folder. sync never changes a folder it did not install, even when a manifest names a skill of the same name. OpenCode also reads the .claude and .agents skill folders and prefers its own, so sync does not install a skill for OpenCode while you have a hand-written one of that name there.
sync keeps a skill that was deprecated, or a pin to a deprecated version, and warns about it. It removes the folders it installed for a skill that was retired or purged, for a pin to a retired or purged version, or for a skill you may no longer read, and prints why. Neither of these makes sync fail; take the entry out of the manifest.
When the registry cannot be reached, or your sign-in has expired, sync prints one line saying why and exits 0. The skills the last sync installed stay in place and keep working.
When the registry stops answering partway through, sync keeps anything it already installed and leaves the rest as the last sync left them. Each folder holds a whole version. sync says it stopped and exits non-zero.
Do not commit synced folders. In each repository folder above, add a .gitignore entry for every skill the repository manifest names, such as .claude/skills/pdf-forms. Each clone then installs its own. Add .rpai-skill-* in those folders too, for the work folders sync unpacks in.
sync removes only folders it can see in this run, in this repository and in your current user folders. A repository you moved or deleted, or a CLAUDE_CONFIG_DIR or XDG_CONFIG_HOME you changed, keeps the folders sync put there. So does a coding agent sync now skips because it is not installed.
Neither file holds a token. sync uses your sign-in.
Run rpk ai skill init once to have your coding agents run sync whenever a
session starts.
Examples
This section provides examples of how to use rpk ai skill sync.
rpk ai skill sync
rpk ai skill sync
Global flags
| Value | Type | Description |
|---|---|---|
|
string |
Redpanda or |
|
stringArray |
Override |
|
bool |
Ignore |
|
string |
|
|
bool |
Enable verbose logging. |