Agentic Data Plane

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

Claude Code

Codex

OpenCode

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

Claude Code

$CLAUDE_CONFIG_DIR/skills, else ~/.claude/skills

Codex

~/.agents/skills

OpenCode

$XDG_CONFIG_HOME/opencode/skills, else ~/.config/opencode/skills

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.

Usage

rpk ai skill sync [flags]

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

--config

string

Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml.

-X, --config-opt

stringArray

Override rpk configuration settings; -X help for detail or -X list for terser detail.

--ignore-profile

bool

Ignore rpk.yaml and redpanda.yaml; use default settings.

--profile

string

rpk profile to use.

-v, --verbose

bool

Enable verbose logging.