# Routines Builder > Use when someone wants to set up recurring/automated cadence — build, optimize, or audit a Claude Code Routine (cloud scheduled agent via /schedule), a local hook, a /loop, or a daily-*/weekly-* ritual skill. Triggers on "schedule this", "automate X weekly", "make my AIOS run itself", "wire a recurring job", "attack our cadence gap". Runs a decision gate and Discovery Interview, then a mandatory supervised test before arming anything. - Skill: `gerardordz96/routines-builder` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add gerardordz96/routines-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/gerardordz96/routines-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: GerardoRdz96 (https://skillmd.com/u/gerardordz96) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gerardordz96/routines-builder --- ## What This Skill Does Designs, ships, optimizes, and audits **recurring automations** so the AIOS runs without being asked — the Cadence pillar of the Four Cs. It's part of the builder family (`/skill-builder`, `/agent-builder`, `/agents-team-builder`, `/hooks-builder`, `/plugin-builder`, `/workflow-builder`) — that family picks the *mechanism*; this one is the cadence/scheduling specialist: **decision gate and Discovery Interview first, a mandatory supervised test before anything fires, files/schedules last.** The headline mechanism is **Claude Code Routines** — saved tasks that run on Anthropic's cloud on a schedule, even with your laptop closed, **fully autonomous and acting AS you**. That power is exactly why this skill never arms a schedule until a supervised "Run now" has passed. Full mechanics (triggers, environments, network modes, connectors, limits, what won't work) are in [reference.md](reference.md). Use this whenever: - Wiring a new recurring trigger (cloud routine, hook, loop, or ritual skill) - Deciding **which** cadence mechanism fits a job - Optimizing or auditing an existing routine - Closing a Cadence gap surfaced by `/aios-audit` --- ## Quick Start: the four cadence mechanisms | Mechanism | Runs on | Needs machine on? | Needs open session? | Min interval | Best for | |---|---|---|---|---|---| | **Cloud Routine** (`/schedule`) | Anthropic cloud | No | No | 1 hour | True autonomy — repo-centric work that lands as a reviewable `claude/` branch + session | | **Hook** (`.claude/settings.json`) | Your machine | Yes (at the event) | No | event-driven | React to an event (SessionStart, PreToolUse, file write) | | **`/loop`** | Your machine | Yes | Yes | 1 min | Polling / babysitting within an active session | | **Ritual skill** (`daily-*`/`weekly-*`) | Your machine | Yes | Yes (you trigger) | manual | A consistent SOP you run by hand; `/aios-audit` counts it toward Cadence | **Important reality:** cloud routines **can't reach local MCP, localhost, or your `.env`**, and everything posts **as you**. They shine on work reachable through a GitHub repo or an API. Anything that needs local-only services or a tool with no API won't ride along until a cloud Connector or API exists. --- ## Mode 1: Build a Routine ### Step 0 — The Decision Gate (FIRST) Pick the right mechanism before scoping anything: 1. **Is the work reachable from a GitHub repo or a plain API, and valuable run unattended?** → **Cloud Routine** (`/schedule`). This is the default for real autonomy. 2. **Does it need local files, localhost, or your local MCP servers?** → a cloud routine **can't** do it. Use a **hook**, **`/loop`**, or a **ritual skill** locally. 3. **Is it reacting to a local event** (session start, a file changed)? → **hook**. 4. **Is it polling something during a session you're already in?** → **`/loop`**. 5. **Is it really a manual SOP you just want to run consistently?** → a **ritual skill** named `weekly-*`/`daily-*` (no true automation, but `/aios-audit` credits it). State one sentence on the chosen mechanism and why. If cloud-routine is chosen, continue below. (For hook/loop/ritual, hand off to `/hooks-builder` for hooks, `/loop`, or `/skill-builder` for a ritual skill — and still do the discovery + test discipline.) ### Step 1 — Discovery Interview (cloud routine) Ask with AskUserQuestion, one round at a time, skipping what's already known. **Round 1: Job & cadence** - What exactly should the routine do, start to finish? (One job. If it's two, that's two routines.) - How often? (cron preset or natural language; **min 1 hour**. Respect daily caps: Pro 5 / Max 15 / Team 25 / Enterprise 25 runs/day.) - Also trigger on a GitHub event or API call? (e.g. "weekly AND on every new PR") **Warning:** a from-fork / public-PR trigger feeds *untrusted* input into a routine that runs and posts **as you** — that's the lethal trifecta (`SECURITY.md`). For any such trigger, **exclude forks** (use the from-fork PR filter), keep the routine on **Trusted** network, and make it **draft-only**. Loop discipline: `references/agent-loops.md`. **Round 2: Repo & scope** - Which repo does it clone? (Your own AIOS repo is a good default for self-running rituals.) Consider a **lean dedicated repo** if the target's `CLAUDE.md` would drag in irrelevant context. - What files/dirs is it allowed to touch? What is off-limits? **Round 3: Environment & secrets** - Does it need external APIs or secrets? The fresh clone has no `.env`, so the prompt must say "don't look for a `.env`." But **do not paste credentials into cloud env vars either** — Anthropic documents those as readable by anyone using the environment and explicitly not a secrets store. Use an official connector, the product's scoped GitHub access, or a real secret manager; keep env vars for non-secret config. - Network mode: **Trusted** (GitHub + Anthropic + connectors only — the default, fine for repo-only work) or **Full** (needed for external APIs)? - Setup script needed before each run? (`npm install`, `pip install`.) **Round 4: Output & failure path** - What does success look like, concretely? Success must be a **boolean, a metric, or a named artifact** (e.g. "push to a `claude/audit-YYYY-WW` branch, open a draft PR summarizing the score delta"). Reject any "run until satisfied / keep iterating" framing — **a routine is single-pass, not iterate-until-done; that's a loop, see `references/agent-loops.md`.** - Where does output land? (`claude/` branch, a connector post, a notes file committed back as a memory trail.) - **What should it do on failure?** There are no automatic retries — bake a fallback into the prompt ("if X fails, log it and stop" / "notify me"). **Round 5: Identity & safety** - It runs and posts **as you**. Confirm any comms/connector actions are OK to carry your name. **Permanent rule (not a starter setting):** anything that **sends/posts/deletes/pays/deploys** ships as **branch or draft output** OR behind a **per-run human gate** — never silent auto-action, no "until trust is established" graduation. **Round 6: Confirmation** — summarize: ``` ## Routine Summary: [name] **Mechanism:** Cloud Routine (/schedule) **Job (one sentence):** [what it does] **Triggers:** [schedule + any GitHub/API] **Repo:** [owner/repo] **Touches:** [allowed] / **Off-limits:** [forbidden] **Environment:** [env vars? network mode? setup script?] **Output:** [claude/ branch / PR / connector / notes] **On failure:** [fallback] **Runs as:** you — [comms confirmed Y/N] ``` Proceed only on confirmation. ### Step 2 — Write the routine prompt The **prompt IS the routine.** Write it as a one-shot the agent can finish without you: - Be specific; name files/dirs; state what success looks like. - Set boundaries ("only modify X, don't touch Y"). - Include the output format ("push to `claude/...`, open a draft PR with a summary"). - Tell it where secrets live ("API key is an env var — use it directly, no `.env`"). - Say what to do on failure. - **Design the verification into the prompt:** a functional **boolean/metric self-check** the run does first (did the artifact get produced? did tests pass?) → where judgment is needed, route the check to a **different-lineage judge** (not the model that did the work, to dodge same-blind-spot self-review) → land the result behind a **human gate** (draft PR / `claude/` branch). A routine that can't state its own done-check shouldn't be armed. See `references/agent-loops.md` (the *observe* beat). - Put **stable** rules in the repo's `CLAUDE.md` (read automatically on the fresh clone); keep **run-specific** instructions in the prompt. Don't duplicate. ### Step 3 — Environment setup (manual, at claude.ai — flag clearly) If the routine needs env vars, a network mode change, or a setup script, those are configured in the **claude.ai web UI before creating the routine** — the AIOS cannot set these programmatically. Hand the user the exact list of env-var names and network mode to set, and pause until confirmed. Repo-only routines (e.g. the self-audit) need none of this. ### Step 4 — Create + the MANDATORY supervised test Create the routine via the **`/schedule`** skill (the terminal path to Routines). For **event-triggered** routines (GitHub/API), create them with the **triggers DISABLED** so a real event can't fire before you've watched a supervised run. Then, before the schedule is armed: 1. **"Run now"** and watch one execution live. 2. Verify it read `CLAUDE.md`, stayed in scope, produced the agreed output on the `claude/` branch / session. 3. **Test the failure path**, not just the happy path. 4. Confirm secrets resolved from env vars (if any) and the network mode was sufficient. **This test is a hard gate.** Do not arm a recurring schedule until a supervised run passes. (This is the one place routines-builder never skips, even when asked to "just schedule it.") ### Step 5 — Arm the schedule Once the supervised run passes, set the recurring schedule via `/schedule` — and **now** enable any GitHub/API triggers you created disabled in Step 4. Confirm back to the user: cadence, repo, next fire time, daily-cap headroom, and how to review/pause it. ### Step 6 — Document & register Write the routine's definition to **`routines/.md`** — the single source of truth, matching `routines/README.md`'s schema: **what it does**, **when it fires** (cadence + any GitHub/API triggers), **what it produces** (output location), plus repo and the verification/human-gate from Step 2. Then add just a **one-line cross-link** to that file in `CLAUDE.md`'s "Your routines / cadence" area — don't duplicate the body. The `routines/.md` file is what lets `/aios-audit` credit the Cadence pillar. --- ## Mode 2: Optimize a Routine - **Burning the daily cap / tokens** → widen the interval, narrow the prompt scope, or split into a leaner repo. - **Stops to ask questions** → the prompt isn't one-shot; make it self-sufficient with explicit success criteria. - **Fails silently** → add a failure fallback ("if X, log and notify me"). - **`.env` errors** → move secrets to cloud env vars; tell the prompt to read them directly. - **Blocked outbound calls** → switch Trusted → Full (and weigh the exfiltration risk for untrusted inputs). - **Bloated context** → trim the repo's `CLAUDE.md` or point at a dedicated lean repo. ## Mode 3: Audit Cadence - [ ] At least one real recurring trigger exists (routine / hook / loop / ritual skill) - [ ] Each cloud routine has passed a supervised "Run now" - [ ] Secrets are in cloud env vars, never committed `.env` - [ ] Network mode is the minimum needed (Trusted unless an external API requires Full) - [ ] Every routine prompt is one-shot with an explicit failure path - [ ] Comms/connector actions that post **as you** were tested before being wired - [ ] Routines push only to `claude/`-prefixed branches; bearer tokens not leaked - [ ] Each routine has a `routines/.md` definition (cross-linked from CLAUDE.md) so `/aios-audit` can see it --- ## Reference Recipe: Weekly Self-Audit The canonical first routine (closes the Cadence gap): - **Repo:** your own AIOS repo **Cadence:** weekly **Network:** Trusted (repo-only) **Env vars:** none - **Prompt (one-shot):** "Run the /aios-audit skill on this repo. Then do decisions-log housekeeping: flag any decision older than 30 days with no follow-up. Write the audit report to `audits/audit-.md`. Push to a `claude/weekly-audit-` branch and open a draft PR titled 'Weekly audit ' summarizing the score and the delta vs the previous audit. If /aios-audit can't run, log why in the PR body and stop. Do not modify any file outside `audits/`." - **Output:** reviewable `claude/` branch + draft PR each week. Nothing merges without you. --- ## Important Notes - **Decision gate is not optional** — most "schedule this" asks for *local* work belong to a hook, `/loop`, or a ritual skill, not a cloud routine. - **The supervised "Run now" test is a hard gate** before arming any schedule, even on "just schedule it." - **Everything runs as you.** Branch/draft output (or a per-run human gate) is the permanent rule for any send/post/delete/pay/deploy; test before wiring any comms connector. - **Secrets → cloud env vars, never `.env`.** Never commit `.env` to "solve" a missing-key error. - Cloud routines can't reach local MCP, localhost, or local files — only what's in the repo or an API. - For the full triggers / environments / network / connectors / limits reference, see [reference.md](reference.md).