rpk-author

name	rpk-author
description	Turn a git repository into an rpk package by scaffolding the .rpk/ directory. Trigger when the user wants to package a project for rpk, convert a GitHub clone into an rpk package, "make this an rpk package", or add/edit the .rpk/ folder of a repo. Also trigger when the user is inspecting an unfamiliar .rpk/ directory and wants guidance.

rpk-author

Create or update the .rpk/ directory in a git repository so it can be versioned, built, and installed by the rpk package manager.

Prerequisites: This skill covers scaffolding. For ongoing development workflow (editing, staging, testing), see the rpk-developer skill first.

When to use

• "Make this an rpk package"
• "Add rpk packaging to this repo"
• "Package for rpk"
• "Set up .rpk/ for this project"
• "Publish this to my rpk bare repos"

Guardrails

• Read PACKAGING.md first. Do not act from memory. Locate it:
  • ~/.local/share/doc/rpk/PACKAGING.md (user install)
  • /usr/local/share/doc/rpk/PACKAGING.md (system install)
  • docs/PACKAGING.md in the rpk source repository
• Don't invent commit SHAs. Every entry in .rpk/versions must come from git rev-parse <ref>^{commit} run against the actual repository.
• Don't invent install prefixes. If the build system doesn't accept a custom prefix, stop and report — do not fake $TARGET by hand-copying files unless the user explicitly asks for that fallback.
• Build systems must NOT run stow. make install writes directly into the prefix directory ($PREFIX normally, $TARGET during packaging). Rpk handles stow. The Makefile must not.
• Never touch target symlinks manually. Do not create, remove, or modify symlinks in the target tree (~/.local/etc/, ~/.local/bin/, etc.) by hand. These are owned by rpk/stow. Always use rpk update <pkg> or rpk install <pkg> to manage them.
• Don't commit without confirmation. Scaffold, verify, then ask. Exception: the user runs rpk patch / rpk minor / rpk major themselves — the agent never manually commits or tags.

Workflow

1. Read PACKAGING.md end-to-end (especially the "Authoring a package from an upstream repository — agent playbook" section).
2. Identify the project's build system (configure.ac, CMakeLists.txt, Cargo.toml, go.mod, package.json, pyproject.toml, Makefile with PREFIX, or pure scripts).
3. Seed versions from git tag -l or the project's explicit version files. Resolve each to a commit SHA.
4. Scaffold .rpk/type, .rpk/versions, .rpk/package (using the cookbook recipe matching the build system), .rpk/install (optional post-stow hook for dotfiles outside the stow prefix), .rpk/delete (reverse install actions), and .rpk/depends/* for OS prerequisites. Package commands inside scripts must use verb-first syntax: rpk commit "$PACKAGE" "$VERSION", not rpk commit "$VERSION".
5. Smoke-test locally:

   rpk init
   rpk depends <pkg>
   rpk package <pkg> <latest-version>
   rpk install <pkg>
   

6. Report what you scaffolded and what to verify before committing. Ask before git add / git commit / git push.

Working inside the rpk repository (self-hosting)

When the agent is working inside the rpk source repository and has made code changes (fixes, features), use the rpk release workflow:

1. Commit changes in the dev clone normally (git commit)
2. Push to bare — git push local master
3. Bump version — rpk patch rpk (operates on the worktree at ~/.local/src/rpk, NOT the dev clone)
4. Sync dev clone — git pull --rebase local master
5. Publish — git push origin master
6. Install — rpk update rpk

Never manually edit VERSION or .rpk/versions. The rpk patch command handles both, commits them in the worktree, and records the correct SHA in the ledger. Agent interference breaks the version → commit mapping and causes installed bundles to have stale VERSIONs.

If .rpk/versions points to wrong commit: This means the agent manually edited it. Fix by running rpk patch rpk properly from worktree or manually updating the SHA to match the commit that has the correct VERSION file content.

Ongoing maintenance (after initial scaffold)

The user bumps versions with the rpk CLI — the agent never does this manually:

rpk patch    # 1.0.0 → 1.0.1 (patch)
rpk minor    # 1.0.0 → 1.1.0 (minor)
rpk major    # 1.0.0 → 2.0.0 (major)

These update .rpk/version, append to .rpk/versions, commit, and tag. After pushing, rpk update <pkg> builds the new bundle and installs it.

Important: changing .rpk/package in the worktree does not affect already-built bundles in ~/.local/pkg/. A new version must be built for the fix to take effect.

For the development workflow (edit → stage → test → release), see the rpk-developer skill, which covers the four-directory model and when to use rpk stage vs rpk install vs rpk update.

Shell safety for .rpk/install and .rpk/delete

Both hooks run with set -eu by convention. The && short-circuit operator is the last command in the script, and its left-hand side returns non-zero, set -e aborts the whole script. Example:

# DANGEROUS — exits 1 when the directory does not exist:
[ -d "$ETC/bash" ] && ln -sf "$ETC/bash" "$HOME/.bash"

Fix: always end the script with true:

[ -d "$ETC/bash" ] && ln -sf "$ETC/bash" "$HOME/.bash"
true

Common failure modes

• "version X has no commit hash" — the ledger line is missing its tab + SHA column.
• Empty bundle after rpk package <pkg> — the build didn't honour $TARGET; check the prefix flag wiring.
• Stow conflict on install — another installed package claims the same path. Uninstall the conflicting one or rename.
• "install script failure" — .rpk/install exited non-zero. Debug by running bash -x .rpk/install from the worktree.
• Old bundle still installed after fixing .rpk/package — a new version must be built. rpk patch and rpk update <pkg>.

Related skills

• rpk-developer: Development workflow, four-directory model, testing
• rpk-testing: Pre-push test tiers and CI reproduction

CLI reference

man rpk for the full command surface.