ckb/.agents/skills/ckb-routine/SKILL.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

6.3 KiB

name description
ckb-routine Set up, list, run or remove routines — KB actions ("Lint", "Index external sources", any routing-table phrase) that fire automatically at session start once a period has elapsed since they last ran. Definitions and the last-run date live in ckb.yaml under routines:, committed and shared by everyone using the repo. Use for "every week run lint", "lint automatically every 7 days", "add a routine", "list routines", "what routines are set up", "which routines are due", "run the routines now", "remove the weekly lint", "stop the monthly index". Not Claude Code's cloud scheduler or /loop — a routine needs no running agent; it is checked whenever someone opens a session.

Routine skill

Purpose

A routine is time-since-last, not a calendar: it fires at the first session start after every has elapsed since last_run, nothing runs while nobody is working in the KB, and a run by one person counts for everyone because the state is committed.

Where routines live

ckb.yaml, block routines:, owned by this skill:

routines:
  - name: weekly-lint
    do: "Lint"              # any phrase from the AGENTS.md §3 routing table, or a plain instruction
    every: 7d               # Nh | Nd | Nw — day granularity; 24h behaves like 1d
    confirm: false          # true: ask at the end of the reply instead of running
    last_run: 2026-10-21    # set by --mark when the action completes; blank = never ran

do is executed exactly as if the user had typed it, so it routes through the same table ("Lint" → ckb-lint, "Index external sources" → ckb-index-external, "Give me a project summary" → ckb-project-summary). Two actions are refused by the script: anything naming ckb-reset or ckb-sync-changes — one is destructive, the other touches the remote.

The script

<python> .agents/skills/ckb-routine/scripts/routines.py --due            # due routines, one per line; exit 1 if any
<python> .agents/skills/ckb-routine/scripts/routines.py --list           # all routines with last run and next due date
<python> .agents/skills/ckb-routine/scripts/routines.py --mark <name>    # last_run = today
<python> .agents/skills/ckb-routine/scripts/routines.py --add --name <name> --do "<phrase>" --every 7d [--confirm]
<python> .agents/skills/ckb-routine/scripts/routines.py --remove <name>

All edits are line-level and leave the rest of ckb.yaml byte for byte (template:, kb_modules:, conversations: belong to other skills). Never hand-edit the block — use the script, so the file stays parseable by it. Resolve <python> as AGENTS.md §3 describes; without Python, routines are simply not checked — say so once per session.

How to run this skill

Add ("every week, lint" / "index external sources monthly, but ask me first")

  1. Derive name (lower-case, hyphens: weekly-lint), do (the routing phrase, quoted) and every (7d, 2w, 30d). "Ask me first" → --confirm.
  2. Run --add. On "already exists", offer --remove then --add.
  3. Confirm in one line. Say that last_run is blank, so it fires at the next session start — or offer --mark <name> now if the user just did the action by hand and wants the clock to start today.
  4. ckb.yaml changed: mention it in the workload note. It is a template file, not wiki/, so wiki/log.md is not touched.

List / which are due

--list and relay it. DUE rows are what will run at the next session start; [confirm] rows will be asked about instead.

Remove

--remove <name>, confirm in one line. Removing the last routine leaves routines: [].

Run now ("run the routines", "run the weekly lint now")

Perform do for the named routine (or every due one) in this turn, then --mark each one that completed. A routine that is not yet due can still be run on request — marking it restarts its period from today.

The firing rule (what Rule E does at session start)

  1. Session start runs --due (through ckb-lint/scripts/session_start.py). Exit 0 or no block: nothing to do, stay quiet. Exit 1: remember the due list; finish the user's request first.
  2. Then, in the same turn, for each due routine:
    • confirm: false — perform do through the normal skill, run --mark <name>, and add one line to the reply: Routine weekly-lint ran: <one-line result>.
    • confirm: true — do not run it. End the reply with one question: "Routine <name> (<do>) is due — run it now?" On a yes in the next turn, run and mark. On a no, say it will be asked again next session and leave last_run alone. In a non-interactive session, skip confirm: true routines and note that in the workload note.
  3. Only a completed action is marked. If the skill fails, is declined, or stops for input it never gets, last_run stays as it was so the routine comes back next session — say so in one line.
  4. Manual runs count. Whenever a skill is run for any reason and some routine's do names that action (the user said "Lint" themselves), run --mark for that routine too. One lint a week is the point, not one lint a week plus whatever the user did by hand.
  5. Logging: the action's own skill logs whatever it changes under wiki/ as usual (Rule B); write **Source:** routine <name> (<skill>) on those entries so the log shows it was not a human request. The workload note gets one line per routine fired.

Edge cases

  • Unreadable every or last_run — --list shows the problem text in place of the next date; --due treats an unreadable last_run as "never ran" (so it fires) and an unreadable every as "never due" (so it does not). Tell the user and offer to fix the value with --remove/--add.
  • Two people fire the same routine the same day — both --mark the same line to the same date; git merges that cleanly. Different dates conflict on one line; the later date is the right resolution.
  • ckb-upgrade and ckb-module never touch routines:; ckb-init writes routines: []; ckb-reset keeps ckb.yaml (tier 6, default no).
  • Claude Code's schedule / /loop are a different thing: they need a running agent and live outside the repo. A routine is the right tool when the action should happen "whenever someone next opens this KB after N days", shared by the whole team.