From f5b7704647df4a9705bb18e4eb565a0c6221e371 Mon Sep 17 00:00:00 2001 From: Valentin Haudiquet Date: Tue, 22 Sep 2026 23:55:56 +0200 Subject: [PATCH] data: add an agent SKILL.md teaching pkh usage Add data/skill/SKILL.md in the agent-skills open format: a skill directory that agents (Claude Code, Codex, OpenCode, ...) discover and load on demand. It documents the shared option surface, the pull, chlog, build, deb, lint, put workflow and the flags that keep runs non-interactive; the command reference was generated from the live --help output of every subcommand. It lives under data/ so a later module can embed it and ship it with the binary, for example a 'pkh skill' installer writing it into the agent skill directories. --- data/skill/SKILL.md | 130 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 data/skill/SKILL.md diff --git a/data/skill/SKILL.md b/data/skill/SKILL.md new file mode 100644 index 0000000..54030c3 --- /dev/null +++ b/data/skill/SKILL.md @@ -0,0 +1,130 @@ +--- +name: pkh +description: 'Drive pkh, a Debian/Ubuntu packaging helper: pull source packages, generate changelog entries, build .dsc/.deb, lint, and upload to a PPA. Use it whenever the task touches Debian or Ubuntu packaging: patching an existing package, preparing an SRU, backport or NMU, scaffolding a new .deb, rebuilding for a PPA, or uploading a source package. Trigger on "update the changelog", "package this", or a bare package name, even when the user never mentions Debian.' +--- + +# pkh + +`pkh` wraps the Debian packaging toolchain (`dch`, `dpkg-buildpackage`, +`sbuild`, `dpkg-source`, `quilt`, `lintian`, PPA uploads) in one CLI. +The subcommands share one set of option names, so `-s` always targets +the series and `--ppa` always names the PPA. Each step also does more +than the raw tool it replaces: `pull` fetches the orig tarball with the +source, `chlog` commits the entry it writes, `deb` sets up a chroot and +installs the build dependencies. + +Check the install with `pkh --version`. Each command lists its flags +with `pkh --help`, so check there instead of guessing. pkh +shells out to host tools (git, dpkg-dev, quilt, mmdebstrap, lintian, +pristine-tar, schroot, ...). Install the ones your workflow uses, or +use the classic snap, which carries them. + +## Shared options + +| Option | Meaning | +|---|---| +| `-d, --dist ` | Target distribution, `debian` or `ubuntu` | +| `-s, --series ` | Target series, for example `resolute` or `noble` | +| `-v, --version ` | Target package version | +| `-a, --arch ` | Target architecture, for example `amd64` or `riscv64` | +| `-p, --pocket ` | Distribution pocket: `updates`, `security`, `proposed` | +| `--ppa ` | Act on the named PPA | + +Defaults come from the host vendor, its development series, and its +architecture. When the target differs, pass the flags: packaging for +Ubuntu on a Debian host needs `-d ubuntu`, and a series or architecture +that differs from the host needs `-s` or `-a`. + +## Patch an Ubuntu package + +``` +pkh pull hello # source and orig tarball; add -d ubuntu off an Ubuntu host +# edit the package, committing each patch to git +pkh chlog # generates the entry, opens it for editing, commits it +git add debian/changelog && git commit -m "d/changelog" +pkh build # source package, written next to the tree +pkh deb # binary build in a chroot with build deps installed +pkh lint # lintian plus pkh-native checks +pkh put --ppa user/hello_xxx # uploads the .changes file from the build +git push xxx user-fork # push the branch to your fork +``` + +Run `pkh chlog` and `pkh build` from the root of the source tree; they +act on the package in the current directory. + +## Command reference + +- `pkh new [name]` scaffolds a buildable source package. `--lang` + picks the build system (`rust`, `python`, `meson`, `cmake`, + `autotools`, `go`, `shell`, `makefile`); `--source ` packages + existing sources instead. `--upstream-version` and `--revision` set + the version. `--description`, `--homepage`, `--license `, + `--command`, `--maintainer "Name "`, and `--depends` fill in + the package metadata, with the maintainer defaulting to + `DEBFULLNAME`/`DEBEMAIL` and then git config. `--quilt` and + `--native` choose the source format; `--orig-from + release|git|path|snapshot` and `--orig-path` control the orig + tarball. The changelog starts as `UNRELEASED`; `--release` targets + `--series` instead. `--defaults` answers every remaining question + with its default, which keeps the run non-interactive. + +- `pkh pull ` fetches a source package from the archive or + git. `--archive` skips git. `--ppa user/ppa` and `--repository + ` pull from a PPA or an external flat repository instead. + `-d`, `-s`, `-v`, and `-p` target an exact source. + +- `pkh chlog` generates the changelog entry from the commits since the + last version tag, opens it for editing, and commits it. `--backport`, + `--nmu`, and `--rebuild` apply the matching numbering scheme + (`3.1-1ubuntu2~24.04.1`, `1.0-1.1`, `1.0-1build1`); `-v` sets an + explicit version instead. + +- `pkh build` produces the .dsc. `--orig auto|always|never` controls + whether the upload includes the orig tarball; the default, `auto`, + includes it only when the upstream version changed. + +- `pkh deb` builds the binary packages in an isolated context with the + build dependencies installed. `--ppa` (repeatable) adds dependency + sources, `--inject ` preinstalls a package, and `-j` + caps parallel jobs. `--cross` cross-compiles instead of using + qemu-binfmt, but most packages cannot cross-compile, so prefer qemu. + Leave `--mode` unset unless you need a specific build context. + +- `pkh lint [path]` runs lintian plus the pkh-native checks. `--json` + emits a machine-readable report and `--list-tags` prints the native + tag catalog. `--fail-on` sets the severities that fail the run + (errors by default), `--suppress-tags` ignores tags, `--check` runs a + single native check, and `--info`, `--pedantic`, and + `--experimental` add detail. `--repack` packs the tree fresh instead + of reusing the existing build output. + +- `pkh put [changes]` uploads a .changes file to `--ppa user/ppa`. + With no argument it uploads the .changes from this package's last + build, found next to the source tree. `--force` re-uploads a file + that was already uploaded. + +- `pkh prune` removes build artifacts and caches. Run it with + `--dry-run` first to list them. `--all` also deletes the cached + chroot tarballs, which take long to download again, so use it when + you need the disk space. + +## Notes for agent runs + +- Pass `-d`, `-s`, and `-a` whenever the target differs from the host, + so runs are reproducible. +- Keep runs non-interactive. Pass explicit flags, use `pkh new + --defaults`, and set `EDITOR` before `pkh chlog` (`EDITOR=true` keeps + the generated text). Commands may ask short questions on the + terminal; flags avoid most prompts. +- Pass `RUST_LOG=debug` for pkh's own logs. `--verbose` on `pkh build` + and `pkh deb` prints raw tool output instead of the live view. +- pkh writes the build artifacts (.dsc, .changes, logs) next to the + source tree. `pkh put` finds them without arguments, and `pkh prune` + removes them again. +- Run `pkh lint` before `pkh put`. It exits nonzero when findings reach + the `--fail-on` level, which defaults to errors. +- pkh intercepts Ctrl+C, runs its cleanup hooks, and exits with status + 130. `pkh prune` removes anything left over. + +The upstream repository is https://git.vhaudiquet.fr/vhaudiquet/pkh. +Its README has longer workflow examples.