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")
- Derive
name(lower-case, hyphens:weekly-lint),do(the routing phrase, quoted) andevery(7d,2w,30d). "Ask me first" →--confirm. - Run
--add. On "already exists", offer--removethen--add. - Confirm in one line. Say that
last_runis 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. ckb.yamlchanged: mention it in the workload note. It is a template file, notwiki/, sowiki/log.mdis 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)
- Session start runs
--due(throughckb-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. - Then, in the same turn, for each due routine:
confirm: false— performdothrough 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 leavelast_runalone. In a non-interactive session, skipconfirm: trueroutines and note that in the workload note.
- Only a completed action is marked. If the skill fails, is declined,
or stops for input it never gets,
last_runstays as it was so the routine comes back next session — say so in one line. - Manual runs count. Whenever a skill is run for any reason and some
routine's
donames that action (the user said "Lint" themselves), run--markfor that routine too. One lint a week is the point, not one lint a week plus whatever the user did by hand. - 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
everyorlast_run—--listshows the problem text in place of the next date;--duetreats an unreadablelast_runas "never ran" (so it fires) and an unreadableeveryas "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
--markthe same line to the same date; git merges that cleanly. Different dates conflict on one line; the later date is the right resolution. ckb-upgradeandckb-modulenever touchroutines:;ckb-initwritesroutines: [];ckb-resetkeepsckb.yaml(tier 6, default no).- Claude Code's
schedule//loopare 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.