| name | caro-scaffold |
| description | Scaffold a new CaroML task file (.caro) from a natural-language description. Use this when the user wants to create a repeatable shell task that Caro will validate, generate, and maintain over time. Triggers on requests like "make a CaroML task that...", "scaffold a runbook for...", "create a .caro file for...", or invocations of `/caro new <name>`. |
CaroML Task Scaffolding
This skill helps you create a new .caro file (a CaroML task) and an
accompanying lock + runbook by walking through the user's intent in a
small number of focused steps.
When to invoke
The user is asking for a repeatable shell task that they'd otherwise
script by hand and gradually drift away from. Examples:
- "Make a CaroML task that cleans up old log files weekly"
- "Scaffold a runbook to deploy the API to staging"
- "Create a .caro for the nightly snapshot job"
Caro's value proposition is that the intent (the what) stays stable
while the generated script can evolve — across model upgrades, new CVE
patterns, platform changes, or learned team preferences. The eight-keyword
DSL (TASK / WHY / NEED / ON / LET / DO / NOTE / REM) is meant to feel like
your first programming language: line-oriented, minimal syntax, BASIC-like.
Workflow
-
Clarify the intent. Ask 1–3 short questions:
- What's the one-line title? (becomes
TASK)
- Why does this task exist? When does it run? (becomes
WHY)
- Does it need sudo / network / a specific tool? (becomes
NEED)
- Target platforms? macOS, Linux, both? (becomes
ON)
-
Sketch the steps. Each DO line is one natural-language intent.
Keep them short and imperative. Order matters — later steps may use
earlier results.
-
Run caro new <name> "<description>" if the user is in a shell
with caro installed. Otherwise, write the file content yourself
following the format below.
-
Show the user the resulting .caro before generating. Let them
refine before committing.
-
Run caro check, then caro generate <name> --backend mock for
a dry-run; show the resulting commands. If anything looks off,
refine the intent (not the output).
-
For real generation, point the user at caro generate with their
configured backend; for now mock is the only one wired through.
File format reference
REM Optional comments anywhere; ignored at runtime
TASK <one-line title>
WHY <reason; when does this run?>
NEED <prerequisite> # zero or more
ON <platform> [PREFER <a, b>] [AVOID <c, d>] # zero or more
LET <name> = <value> # zero or more; use {name} in DO lines
NOTE <hint to the LLM> # attaches to the next DO line
DO <natural-language intent>
DO <next intent>
Recognized platforms: macos, linux, windows, posix.
Example session
USER: Make a CaroML task that deletes log files older than 30 days,
with confirmation per file.
ASSISTANT: A few quick questions:
1. Title for the task? (e.g., "Clean up old log files")
2. Where do the logs live? (`/var/log` is the conventional spot)
3. Target platforms? Both macOS and Linux?
USER: Yes, both. /var/log is fine. Title is "Cleanup logs".
ASSISTANT: Drafting tasks/cleanup-logs.caro:
TASK Cleanup logs
WHY Free disk space; runs weekly via cron
NEED sudo
ON macos PREFER bsd-tools
ON linux PREFER gnu-tools
LET path = /var/log
LET days = 30
DO find log files in {path}
DO filter to those older than {days} days
DO delete each, asking confirmation per file
DO record what was deleted to /tmp/caro-cleanup.log
Want me to commit this as-is, or refine anything first?
Don'ts
- Don't over-constrain — leave the LLM room to choose a sensible idiom.
DO find all .log files older than 30 days and delete them is fine;
DO run "find /var/log -mtime +30 -delete" defeats the point.
- Don't put shell flags in the intent — that's the lock's job.
- Don't ship
.sh runbooks as the primary deliverable. The committed
artifact is the .caro + .caro.lock; runbooks are derived.
Triggers
This skill should activate when the user says any of:
- "make a CaroML task"
- "scaffold a runbook"
- "create a .caro for ..."
- "/caro new"
- "I want a repeatable shell task"
