From tsuku-recipes
Use when writing or modifying tsuku recipe TOML files. The recipe format has 60+ actions, 14 version providers, and platform-conditional logic that tsuku create doesn't fully cover. This skill provides quick-reference tables and bundled references for the cases that need manual authoring.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tsuku-recipes:recipe-authorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Every recipe is a TOML file with four sections:
Every recipe is a TOML file with four sections:
[metadata] # Name, description, platform support
[version] # How to resolve the latest version (often inferred)
[[steps]] # Ordered installation actions
[verify] # Post-install verification command
Optional sections: [[resources]] for extra downloads, [[patches]] for source patches.
Actions are the building blocks of [[steps]]. Each step has an action field
and action-specific parameters.
| Action | Description |
|---|---|
github_archive | Download and extract a GitHub release asset |
github_file | Download a single file from a GitHub release |
download | Download from any URL with {version}, {os}, {arch} placeholders |
download_archive | Download + extract + install binaries in one step |
fossil_archive | Download from a Fossil SCM tarball endpoint |
| Action | Description |
|---|---|
cargo_install | Install a Rust crate via Cargo |
npm_install | Install an npm package globally |
pipx_install | Install a Python package in an isolated venv |
go_install | Install a Go module |
gem_install | Install a Ruby gem |
cpan_install | Install a Perl distribution |
nix_install | Install via Nix (Linux only) |
| Action | Description |
|---|---|
homebrew | Download a Homebrew bottle (macOS and glibc Linux) |
apt_install | Check for Debian/Ubuntu packages |
apk_install | Check for Alpine packages |
dnf_install | Check for Fedora/RHEL packages |
pacman_install | Check for Arch packages |
zypper_install | Check for openSUSE packages |
brew_install | Check for system Homebrew packages (macOS) |
brew_cask | Install macOS GUI apps via Homebrew Cask |
| Action | Description |
|---|---|
configure_make | Autotools-style ./configure && make |
cmake_build | CMake build |
meson_build | Meson + Ninja build |
setup_build_env | Configure PATH/CFLAGS/LDFLAGS from dependencies |
| Action | Description |
|---|---|
install_binaries | Copy binaries to install dir; register for PATH symlinking |
chmod | Set file permissions |
set_rpath | Modify ELF RPATH for library resolution (Linux) |
set_env | Export environment variables via env.sh |
text_replace | Find/replace in files |
install_shell_init | Write shell initialization scripts |
install_completions | Write shell completion scripts |
homebrew_relocate | Fix @@HOMEBREW_PREFIX@@ paths in bottles |
| Action | Description |
|---|---|
app_bundle | Install a macOS .app bundle from ZIP/DMG |
run_command | Execute a shell command |
require_system | Validate a system dependency exists |
require_command | Check that a command is in PATH |
See references/action-reference.md for full parameter tables and usage notes.
The [version] section controls how tsuku resolves the latest version.
Most providers auto-detect from actions -- you can often omit [version] entirely.
| Source | Resolves From | Auto-Detects From |
|---|---|---|
github | GitHub releases/tags | github_archive, github_file |
npm | npm registry | npm_install |
pypi | PyPI | pipx_install |
crates_io | crates.io | cargo_install |
rubygems | RubyGems.org | gem_install |
goproxy | proxy.golang.org | go_install |
metacpan | MetaCPAN | cpan_install |
homebrew | Homebrew API | homebrew |
cask | Homebrew Cask API | -- (set cask field) |
tap | Third-party Homebrew tap | -- (set tap + formula) |
fossil | Fossil VCS timeline | fossil_archive |
nixpkgs | NixOS channels | -- |
go_toolchain | go.dev/dl | -- |
When auto-detection works, skip the [version] section. Override with explicit
fields when the inferred source is wrong or you need tag_prefix, github_repo,
or other provider-specific config.
Steps can target specific platforms with a when clause.
[[steps]]
action = "homebrew"
formula = "pcre2"
when = { os = ["linux"], libc = ["glibc"] }
[[steps]]
action = "configure_make"
source_dir = "pcre2-{version}"
when = { os = ["linux"], libc = ["musl"] }
[[steps]]
action = "homebrew"
formula = "pcre2"
when = { os = ["darwin"] }
Available when fields:
| Field | Values | Example |
|---|---|---|
os | ["linux"], ["darwin"] | when = { os = ["linux"] } |
arch | "amd64", "arm64" | when = { arch = "amd64" } |
libc | ["glibc"], ["musl"] | when = { libc = ["musl"] } |
linux_family | "debian", "rhel", "alpine", "arch", "suse" | when = { linux_family = "debian" } |
gpu | ["nvidia"], ["amd"], ["intel"], ["none"] | when = { gpu = ["nvidia"] } |
platform | ["linux/amd64"] | when = { platform = ["linux/arm64"] } |
package_manager | "brew", "apt", "dnf" | when = { package_manager = "apt" } |
Multiple fields AND together. Empty when (or omitted) matches all platforms.
See references/platform-reference.md for the libc decision tree and migration templates.
Every tool recipe needs a [verify] section. Libraries are exempt.
Version mode (default) -- extracts and compares version:
[verify]
command = "trivy --version"
pattern = "{version}"
Output mode -- checks the command runs, no version comparison:
[verify]
command = "mytool --help"
mode = "output"
reason = "Tool prints no parseable version string"
Format transforms -- normalize extracted versions:
| Transform | Input | Output |
|---|---|---|
semver | 1.2.3-beta | 1.2.3 |
semver_full | v1.2.3-beta+build | 1.2.3-beta+build |
strip_v | v1.2.3 | 1.2.3 |
raw | (as-is) | (as-is) |
calver | 2024.01.15 | 2024.01.15 |
Set via version_format in [verify] or [metadata].
Tools that exit non-zero on --version: set exit_code in [verify].
See references/verification-reference.md for the full decision flowchart and common patterns.
Declare dependencies in [metadata]:
[metadata]
dependencies = ["openssl", "zlib"] # needed at install time
runtime_dependencies = ["python-standalone"] # needed when tool runs
extra_dependencies = ["pkg-config"] # extends auto-detected deps
Most ecosystem actions (cargo_install, npm_install, etc.) auto-detect their
toolchain dependency. Use extra_dependencies to add more without replacing
the implicit set.
See references/dependencies-reference.md for library dependencies, build environment setup, and resolution order.
Distribute recipes from any GitHub repo without contributing to the central registry.
Setup:
.tsuku-recipes/ at your repo rootrecipe-name.toml files (filename must match metadata.name)Install syntax:
tsuku install owner/repo # single-recipe repo
tsuku install owner/repo:recipe # named recipe from multi-recipe repo
tsuku install owner/[email protected] # pinned version
tsuku install owner/repo:[email protected] # named recipe + version
First install from an unregistered source prompts for confirmation. Use
tsuku registry add owner/repo to pre-approve, or set strict_registries = true
in $TSUKU_HOME/config.toml to block unregistered sources entirely.
See references/distributed-reference.md for manifest.json, cache behavior, and the trust model.
| File | When to Read |
|---|---|
| action-reference.md | Looking up action parameters or platform constraints |
| platform-reference.md | Writing when clauses, handling glibc/musl splits |
| verification-reference.md | Choosing verification mode or format transforms |
| dependencies-reference.md | Declaring dependencies or building libraries |
| distributed-reference.md | Publishing recipes from your own repo |
| exemplar-recipes.md | Finding a starting-point recipe for your pattern |
Central registry contributors who have the full tsuku repo can find extended
guides in docs/guides/. External consumers who installed this plugin via
sparsePaths won't have access to that directory -- the bundled references
above cover the same material in condensed form.
| Guide | Topic |
|---|---|
docs/guides/GUIDE-actions-and-primitives.md | Deep dive on action types and determinism |
docs/guides/GUIDE-hybrid-libc-recipes.md | Full libc migration templates |
docs/guides/GUIDE-recipe-verification.md | Verification troubleshooting |
docs/guides/GUIDE-library-dependencies.md | Library auto-provisioning internals |
docs/guides/GUIDE-distributed-recipe-authoring.md | Extended distributed authoring guide |
Before submitting a recipe:
tsuku validate path/to/recipe.toml
tsuku validate --strict path/to/recipe.toml # treats warnings as errors
tsuku validate --check-libc-coverage path/to/recipe.toml # library libc coverage
For distributed recipes, test with sandbox mode:
tsuku install --recipe .tsuku-recipes/my-tool.toml --sandbox
npx claudepluginhub tsukumogami/tsuku --plugin tsuku-recipesProvides expertise in Justfile syntax, recipe development, parameters, shebangs for multi-language scripts, and cross-platform task automation with naming conventions and CI/CD integration.
Guides creation of Gemini CLI custom TOML slash commands with syntax, {{args}} arguments, !{ } shell output injection, file injection, and troubleshooting.
Authors and validates multi-step composition specs for orchestrated hatch3r command/skill sequences.