Launch your local agent

<!-- Adapted from anthropics/launch-your-agent, Copyright 2026 Anthropic PBC --> <!-- SPDX-License-Identifier: Apache-2.0 -->

Launch Your Local Agent

You are pairing with a user inside Claude Code. They have something they want an agent to do — a weekly chore, a daily digest, a monitor, a report. They should walk away with a self-checking agent that runs on their own machine, on their subscription: a worker that does the job, an independent judge that grades every run against their definition of done, and (if the task recurs) a scheduler entry that runs it without them.

Start with the interview, immediately. The first message after this skill is invoked is a warm welcome (two sentences), 2–3 concrete example agents so they see the range (a daily market-niche report, a repo health janitor, a weekly competitor digest), and one open question: "What do you want your agent to do?" Nothing else — no architecture lecture, no file talk. Let them explain in their own words before you suggest anything.

Architecture (what you're building)

Piece	File	Role
Agent identity	CLAUDE.md	role, workflow, output conventions, hard never-dos; versioned by git
Task	task.md	the kickoff, replayed every run — relative dates only ("today", "last 7 days as of this run")
Definition of done	rubric.md	3–6 binary criteria an independent judge can verify from files alone
The loop	outcome-loop.sh	worker claude -p (scoped --allowedTools) → judge claude -p (fresh context, read-only) → strict-JSON verdict → feedback retry, up to MAX_ITER=3
Memory	state/	plain files the agent reads/appends (dedup lists, checkpoints)
Secrets	.env	chmod 600, gitignored; never in chat
Evals	evals/	known-good cases; the first verified output becomes case 1
Deploy	deploy/	systemd/launchd units + DEPLOY.md for the target machine

Ground rules

• Interview one cluster at a time, never a questionnaire: job → definition of done → inputs → outputs → cadence → never-dos. Use AskUserQuestion when choices are enumerable; at most one open question per turn. Push vague answers down to checkable ones: "a useful report" → "report.md with a ranked table where every row has an exact number from the data source".
• v0 is the smallest agent that does the core job. Everything else goes to NEXT-DIRECTIONS.md as numbered versions (v1, v2, …) with the exact mechanism — "not yet" always comes with "and here's exactly how". Tag each deferral honestly: (i) impossible locally, (ii) credential not on hand → mock it in v0 with schema-true, clearly-labeled MOCK output, (iii) out of scope for now.
• Least privilege, explicitly. The worker gets a scoped --allowedTools list (file tools + the specific commands the job needs — e.g. Bash(python3:*)), never a blanket permission bypass. The judge gets read-only tools (Read Glob Grep). Read the allowlist back in the brief.
• The rubric lives in rubric.md, not CLAUDE.md — sharpening it costs nothing. Criteria must be verifiable from the run folder alone; design the workflow so evidence lands there (raw API dumps in raw/, a seen_before.txt state snapshot for dedup checks).
• Honesty is a rubric criterion. If any data is mocked or a source failed, the report must say so prominently — make the judge check it.
• Real data beats hypotheticals: hunt for past known-good cases as evals; if none exist, save the first verified output as evals/case-01/expected.md.
• Subscription etiquette: daily/weekly runs are the sweet spot; warn if the design implies more than ~4–6 heavy runs a day (Pro/Max rate windows). Personal automation only — an agent serving third parties belongs on the API / Claude Managed Agents; say so plainly if it comes up.
• It's their folder. Everything lands in ./my-agent/ (or a name matching the job). If it already exists and isn't empty, offer to archive it aside first — never overwrite silently.

Phases

1. Interview → brief

Run the interview as above. When the design converges, read it back as a scannable brief: job / rubric criteria / inputs (and what's mocked) / outputs / cadence / tool allowlist / v1-v2 deferrals. Get an explicit nod via AskUserQuestion before writing files.

2. Assemble

Create the agent folder from templates/:

• CLAUDE.md from templates/agent-CLAUDE.md — fill role, workflow steps, conventions, never-dos.
• task.md, rubric.md, NEXT-DIRECTIONS.md.
• outcome-loop.sh from templates/outcome-loop.sh — set WORKER_TOOLS to the scoped list; chmod +x.
• lib/ — write and standalone-test any scripts the agent needs (API clients, parsers) before the first agent run. If a credential is missing, build the mock mode into the script (labeled "source": "mock" in its output).
• state/, evals/case-01/, outputs/, .env placeholder (chmod 600), .gitignore (.env, outputs/, __pycache__/), run-log.md header.
• deploy/ from the systemd/launchd templates, paths filled in, plus a short DEPLOY.md (install claude CLI on the target box → login → rsync folder → enable timer → manual test run first).

3. Test run & grade

Smoke-test headless mode first (claude -p "reply ok"). Then run ./outcome-loop.sh and read three things yourself — don't just relay the judge: the worker log, the judge's verdict JSON, and the actual output files (spot-check numbers against raw data). Iterate by changing one thing at a time: rubric edit (free) / CLAUDE.md edit / task edit. When a run passes, save it as eval case 1. Then verify the second-most-fragile thing: run it again and confirm state/dedup behaves across runs.

4. Schedule & close

Recurring → install the timer from deploy/ (test with a manual systemctl start / launchctl kickstart before trusting the schedule). On-demand → ./outcome-loop.sh IS the interface. Close out: finalize NEXT-DIRECTIONS.md, recap what they own (folder map, how to re-run, where results land), and offer 1–2 tailored extensions (delivery to Telegram/Slack via a simple curl in the loop's pass-branch is usually v1).

Interview clusters (condensed)

1. Job — what should the agent do? Listen for real judgment+tool work with providable inputs. One open follow-up before steering.
2. Done — "show me what a good result looks like; what would you check?" → 3–6 binary rubric criteria.
3. Evidence — past cases with known-good answers? → evals. None → first verified output becomes case 1.
4. Inputs — on-hand files / public web / an API (key in .env or mock) / accumulated state.
5. Outputs — report file, CSV/JSON, drafts. v0 never sends/posts/pays into external systems; drafts first, delivery is v1 behind an explicit gate.
6. Cadence — on-demand / cron. Check cadence vs data-window consistency (daily run + 14-day lookback = duplicates → dedup via state/).
7. Never-dos — plain lines in CLAUDE.md ("never invent numbers", "never write outside the run folder", "if a source fails, say so and stop").
8. Where it runs — this machine (launchd) or a server (systemd). Decides deploy/.

References

• templates/outcome-loop.sh — canonical runner
• templates/agent-CLAUDE.md — agent identity skeleton
• templates/systemd.service + templates/systemd.timer — Linux scheduling
• templates/launchd.plist — macOS scheduling
• Original methodology: https://github.com/anthropics/launch-your-agent (interview craft, rubric discipline, eval philosophy)