justfile-expert
Just command runner expertise — Justfile syntax, recipes, parameters, modules, shebang recipes. Use when authoring justfiles, project commands, or task automation.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill justfile-expertIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill provides expertise for the `just` command runner and task automation. It includes patterns that execute shell commands from environment variables and local scripts, which can be risky if the execution environment is not fully controlled.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
Justfile Expert
Expert knowledge for Just command runner, recipe development, and task automation with focus on cross-platform compatibility and project standardization.
When to Use This Skill
| Use this skill when... | Use alternative when... |
|---|---|
| Creating/editing justfiles for task automation | Need build system with incremental compilation → Make |
| Writing cross-platform project commands | Need tool version management bundled → mise tasks |
| Adding shebang recipes (Python, Node, Ruby, etc.) | Already using mise for all project tooling |
| Configuring dotenv loading and settings | Authoring the shell itself (pipes, traps, arg parsing) → shell-expert |
| Setting up CI/CD with just recipes | Project already has extensive Makefile |
| Standardizing recipes across projects | Exposing a module for bulk smoke-testing → cli-smoke-recipes |
Core Expertise
Command Runner Mastery
- Justfile syntax and recipe structure
- Cross-platform task automation (Linux, macOS, Windows)
- Parameter handling and argument forwarding
- Module organization for large projects
Recipe Development Excellence
- Recipe patterns for common operations
- Dependency management between recipes
- Shebang recipes for complex logic
- Environment variable integration
Project Standardization
- Golden template with standard naming and section structure
- Self-documenting project operations
- Portable patterns across projects
- Integration with CI/CD pipelines
Recipe Naming Conventions
| Rule | Pattern | Examples |
|---|---|---|
| Hyphen-separated | word-word | test-unit, format-check |
| Verb-first (actions) | verb-object | lint, build, clean |
| Noun-first (categories) | noun-verb | db-migrate, docs-serve |
| Private prefix | _name | _generate-secrets, _setup |
-check suffix | Read-only verification | format-check |
-fix suffix | Auto-correction | lint-fix, check-fix |
-watch suffix | Watch mode | test-watch, docs-watch |
| Modifiers after base | base-modifier | build-release (not release-build) |
Standard and Workflow Recipes
When creating or standardizing a project justfile, open references/standard-recipes.md for the semantic composites (check, pre-commit, ci, clean, clean-all), the standard recipe set, and the section structure.
Key Capabilities
Parameter forms, settings, recipe attributes ([doc], [private], [group], [confirm], platform), and the module system, including that set fallback is not inherited by a module: references/key-capabilities.md.
Essential Syntax
Basic Recipe Structure
# Comment describes the recipe
recipe-name:
command1
command2
Recipe with Parameters
build target:
@echo "Building {{target}}..."
cd {{quote(target)}} && make
test *args:
uv run pytest {{args}}
Interpolation is UNQUOTED — quote anything that can contain spaces
{{...}} splices raw text into the recipe body before the shell parses it,
so a value carrying spaces or quotes word-splits. This bites hardest on the
*args passthrough above, because the error is reported by the called
program rather than by just, which makes it read like a bug in the tool:
# Trap — one argument with spaces arrives as several
caption *ARGS:
./tool.py {{ARGS}}
$ just caption ./data "the subject's face"
tool.py: error: unrecognized arguments: subjects face
The outer shell consumed the quotes (taking the apostrophe with them) and
the / subject's / face arrived as three separate argv entries. Name the
parameters that can contain spaces and run them through quote(), which emits
a properly shell-escaped literal:
# Correct — named params are quoted; trailing flags still pass through
caption DIR SUBJECT="" *ARGS:
./tool.py {{quote(DIR)}} {{quote(SUBJECT)}} {{ARGS}}
quote() covers embedded spaces, ', ", and $. Keep {{ARGS}} bare —
that is what lets several trailing flags expand as separate words — and accept
its corollary: an individual passthrough flag's value must not contain spaces.
When one might, promote it to a named parameter too.
What --list Shows Is ONE Line, and It Is Not Your Comment Block
just --list renders a single description per recipe. With no [doc]
attribute it takes the last line of the comment block immediately above the
recipe — not the first line, and not the block:
| Above the recipe | --list shows |
|---|---|
[doc("Build the release bundle.")] | that text |
| a comment block, no attribute | only its last line |
bare [doc] | nothing |
| nothing | nothing |
So "add a comment before each recipe" is not the same as documenting it. A block that ends in an example or a caveat — the normal way to write one — lists as that fragment:
# Pitch-correct the singing in an MP4. Video is stream-copied.
# just autotune take.mp4 out.mp4 --key C:minor
autotune IN OUT *FLAGS:
$ just --list
autotune IN OUT *FLAGS # just autotune take.mp4 out.mp4 --key C:minor
Add [doc("one line")] as soon as a recipe's comment block exceeds one
line. The block stays where it is and keeps carrying the detail; the
attribute is the only thing --list reads.
The block binds by ADJACENCY, and reassignment is silent. A blank line ends
a block, so inserting a recipe between a block and the recipe it describes
hands the block to the newcomer — the original then lists blank, and nothing
warns. Re-read just --list after inserting a recipe into an existing file.
A recipe with a required positional has no --help form. recipe *ARGS:
forwards --help to the underlying tool, but just refuses the call before the
tool runs once a positional is required:
$ just autotune --help
error: recipe `autotune` got 1 positional argument but takes at least 2
There is no bare-help spelling for such a recipe. Put the flags in its [doc]
or comment block, or add a help recipe that prints them.
Recipe Dependencies
default: build test
build: _setup
cargo build --release
_setup:
@echo "Setting up..."
Variables and Interpolation
version := "1.0.0"
project := env('PROJECT_NAME', 'default')
info:
@echo "Project: {{project}} v{{version}}"
Conditional Recipes
[unix]
open:
xdg-open http://localhost:8080
[windows]
open:
start http://localhost:8080
Gotchas
Sub-justfile settings and nested just -f calls, path arguments that resolve against the justfile directory, top-level backticks that run for every recipe, keep-awake wrappers, and notifier hooks: references/gotchas.md.
Common Patterns
Setup, Docker, database, and CI/release recipes, plus how to pass per-project values into shared imports across modules (parameters, not shared variables): references/common-patterns.md.
MCP Integration (just-mcp)
To let an AI client list and run recipes over MCP instead of reading the justfile, see references/mcp-integration.md.
Agentic Optimizations
| Context | Command |
|---|---|
| List all recipes | just --list or just -l |
| Dry run (preview) | just --dry-run recipe |
| Show variables | just --evaluate |
| Whole parsed justfile as JSON (recipes, params, deps, settings) | just --dump --dump-format json |
| Recipe names only | just --summary |
| Verbose execution | just --verbose recipe |
| Specific justfile | just --justfile path recipe |
| Working directory | just --working-directory path recipe |
| Choose interactively | just --choose |
Best Practices
Recipe Development Workflow
- Name clearly: Use descriptive, verb-based names (
build,test,deploy) - Document what
--listreads: a one-line comment is enough; anything longer needs[doc("...")], or the listing shows only the block's last line - Use defaults: Provide sensible default parameter values
- Group logically: section comments for the file,
[group("name")]for the listing — a flat--liststops being scannable somewhere around 20 recipes - Hide internals: Mark helper recipes as
[private] - Test portability: Verify on all target platforms
Critical Guidelines
- Always provide
defaultrecipe pointing to help - Use
@prefix to suppress command echo when appropriate - Use shebang recipes for multi-line logic
- Prefer
set dotenv-loadfor configuration - Use modules for large projects (>20 recipes)
- Give a recipe a
[doc("...")]when its comment block's last line would not read as a description on its own —--listshows only that line (see "What--listShows" above). To find them:python3 "${CLAUDE_PLUGIN_ROOT}/scripts/just-recipe-help.py" --audit - Include variadic
*argsfor passthrough flexibility - Quote all variables in shell commands —
{{...}}interpolates unquoted, so wrap any parameter that can contain spaces inquote()(see "Interpolation is UNQUOTED" above); bare{{args}}is correct only for space-free passthrough flags
Comparison with Alternatives
Feature table and when to pick Just, Make, or mise tasks: references/comparison.md.
For the golden justfile template, detailed syntax reference, advanced patterns, and troubleshooting, see REFERENCE.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/justfile-expert">View justfile-expert on skillZs</a>