SKILL.md
Justfile
Author and maintain Just task runners. House style matches this repo's root justfile: minimum-version ≥ 1.55.0, default-list, require(), [default] / [doc] / [group] / [arg], prefer [script] for multi-line bodies. Distill casey/Just principles; never paste third-party skill prose or embed the casey README.
Load reference files on demand from the index below — do not load all at once. Frontmatter is for discovery; references carry deep procedure.
Permission posture
write-scoped — may write justfiles; read-only just inspect by default; ask before destructive recipes, deleting a Makefile, or running side-effecting recipes.
Dispatch
| $ARGUMENTS | Mode | |
|---|---|---|
(empty) / help |
Empty-args gallery | |
create [description] |
Create | |
| `edit [path\ | recipe]` | Edit |
migrate [source] |
Migrate | |
check [path] |
Check | |
discover [query] |
Discover | |
| Natural language about justfiles | Auto-detect |
Auto-detection heuristic
- Existing
justfile/Justfile+ modify/fix/rename → edit - "migrate" / Makefile /
package.jsonscripts → just → migrate - "lint" / "check" / "fmt" / house-style audit → check
- "list" / "show" / "what recipes" / dump → discover
- New justfile or "add recipe" without existing file → create
- Pure shell / CI YAML / Make build semantics / mise / Compose → refuse (see negatives)
Empty args
When $ARGUMENTS is empty, show the mode gallery, posture line, critical rules summary, and reference index. Do not invent a mutating default.
Canonical vocabulary
Use these exactly (canonical terms):
| Term | Meaning |
|---|---|
write-scoped |
May write justfiles; ask before destructive runs/deletes |
| house style | This repo's justfile conventions (default-list, [doc], [script], …) |
| discover | Read-only inspect via just --list / --show / --dump |
| migrate | Map Makefile/npm task scripts into Just recipes |
[script] |
Multi-line script recipe attribute (never combine with recipe-level @) |
| opt-in gate | Create-mode confirmations before overwrite or side effects |
Critical rules
- Version-first — run
just --versionbefore using mid-2026 attributes; prefer ≥1.55.0. - Quiet vs script — never put
@on a[script]recipe; use@only for line quieting. - Prefer
[script]for multi-line shell; avoid fragile escaped multi-line recipes. - No blind
--fmt— inspect with--dump/--checkfirst; apply--fmtonly with intent. - Dry-run / inspect before side effects — discover with
--list/--showbefore running recipes that write, delete, or network. - check.py-before-complete — after skill or justfile edits in this repo skill, run
uv run python scripts/check.pyfromskills/justfile/before declaring done. - No secrets in justfiles — use env / dotenv / user-owned secrets; never hardcode tokens.
- Ask before deleting Makefile or other source runners during migrate.
Operator contract
create
- Confirm target path; refuse overwrite without explicit approval.
- Load [references/create.md](references/create.md) (includes opt-in gate).
- Scaffold house-style settings +
[default]list recipe + grouped docs. - Prefer
require("tool")for hard deps; document optional tools.
edit
- Read the target justfile; run discover inspect if recipes unclear.
- Load [references/edit.md](references/edit.md).
- Preserve house settings; migrate Make-flavored
##comment docs to[doc].
migrate
- Inventory Makefile / npm scripts; map to recipes (see [references/migrate.md](references/migrate.md)).
- Keep sources until user approves deletion.
- Convert Make
##help to Just[doc]/default-list— never keep Make comment-docs as the Just help system.
check
- Load [references/check.md](references/check.md).
just --version, then--list/--dump/--checkas needed.- Report house-style gaps; do not auto-
--fmtunless asked.
discover
- Load [references/discover.md](references/discover.md).
- Prefer read-only:
--list,--show,--dump(--dump-format=json),--groups. - Link casey manual for deep semantics: https://just.systems/man/en/
When NOT to use
- Shell script generation →
shell-scripter - Shell convention-only edits →
shell-conventions - CI/CD workflow YAML →
devops-engineer - Make file-timestamp / pattern-rule builds (not task recipes)
- Docker Compose authorship
- Toolchain version management as the product → mise tooling
See [references/when-not-just.md](references/when-not-just.md).
Reference index
| File | Use when |
|---|---|
| [references/discover.md](references/discover.md) | Inspect recipes with just CLI |
| [references/create.md](references/create.md) | New justfile + opt-in gate |
| [references/edit.md](references/edit.md) | Change existing recipes/settings |
| [references/migrate.md](references/migrate.md) | Makefile / npm → just |
| [references/check.md](references/check.md) | Lint / fmt-check / house-style audit |
| [references/when-not-just.md](references/when-not-just.md) | Scope refusals and redirects |
| [references/pitfalls.md](references/pitfalls.md) | Common Just footguns |
| [references/patterns.md](references/patterns.md) | House-style recipe patterns |
Validation Contract
Run from this skill directory before declaring changes complete:
uv run python scripts/check.py
uv run python skills/skill-creator/scripts/audit.py skills/justfile/
uv run python skills/skill-creator/scripts/package.py skills/justfile --dry-runscripts/check.py chains validateskill.py, validateevals.py, package dry-run, and audit. Completion criteria:
uv run python scripts/check.pyexits 0.- Audit grade A (≥90).
- Package
--dry-runreports portable with no errors. - No portable-CLI violations remain under this skill directory.
Example Blocks
When $ARGUMENTS is empty, show:
/justfile/justfile help/justfile create <description>/justfile edit <path|recipe>/justfile migrate <Makefile|package.json>/justfile check [path]/justfile discover [query]
State the write-scoped boundary (justfile writes OK; ask before destructive recipe runs or Makefile deletion) and the validation command:
uv run python skills/justfile/scripts/check.py