From 79163e09e74891486a9273f7cd409b683401e6aa Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 14:55:47 +0000 Subject: [PATCH] Add handler-quiet-output to the built-in skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents narrate far more than anyone reads: the transcript is not the deliverable, and prose there is spent tokens burying information where no one looks. The new skill routes each kind of output to its store — work happens through tool calls; a minimized NOTES.md ledger (one bullet per action, committed with the work) records what happened and how; problems and causes go to memory; status goes to the final checkpoint-sized message the Stop hook captures onto the checkmark; and questions go through the question tool, which reaches the operator as a push notification and an answer prompt in the web and mobile apps instead of stalling silently in the transcript. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01731mKtVzsfeT4Vi3TvkR48 --- CHANGELOG.md | 7 +++++- README.md | 3 ++- src/handler/builtin_skills.py | 43 +++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbdc76d..72879cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,10 +38,15 @@ since its last release: ### Added — built-in operator skills, pre-installed on every deployment -Seven skills now ship inside Handler (`handler.builtin_skills`) and are seeded into +Eight skills now ship inside Handler (`handler.builtin_skills`) and are seeded into the managed skill store on API startup, so every fresh install — and every existing deployment on upgrade — starts with the judgment layer the hard gates can't enforce: +- `handler-quiet-output` — work through tool calls, not prose: the transcript is not + the deliverable. A minimized `NOTES.md` ledger records what happened and how, + problems go to memory, status goes to the checkpoint, and questions go through the + question tool (push notification + answer prompt in the web/mobile apps) — never + typed into the transcript. - `handler-gate-recovery` — respond to a blocked completion/push gate by fixing the real failure; never delete/skip tests, weaken the mise `test` task, or `--no-verify`. - `handler-testing` — every behavior change lands with a test that fails without it; diff --git a/README.md b/README.md index 79a83ba..0bfeefb 100644 --- a/README.md +++ b/README.md @@ -335,7 +335,8 @@ What the dashboard can now do (all state-changing actions require `ADMIN_TOKEN`) choices a human would be asked — always user scope, the instructions' defaults — and reports them in the command result for after-the-fact review. - **Built-in operator skills** ship with Handler and are seeded into the managed store - on API startup (`handler.builtin_skills`): gate recovery, testing standard, + on API startup (`handler.builtin_skills`): quiet output (tool calls + a minimized + `NOTES.md` ledger instead of transcript prose), gate recovery, testing standard, checkpoint quality, memory discipline, mise-task rules, scheduled-run continuity, and secrets hygiene — the judgment layer the hard gates can't enforce. Seeding is idempotent by name, so operator edits and disables survive upgrades; deleting one diff --git a/src/handler/builtin_skills.py b/src/handler/builtin_skills.py index a94d207..916ee50 100644 --- a/src/handler/builtin_skills.py +++ b/src/handler/builtin_skills.py @@ -24,6 +24,49 @@ from .db import repository as repo # minus front-matter (claude_gen adds name/description at sync time). Kept as plain # data so the content is easy to review and diff, exactly like skills_gen._SKILLS. BUILTIN_SKILLS: list[tuple[str, str, str]] = [ + ( + "handler-quiet-output", + "Work through tool calls, not prose: the transcript is not the deliverable. " + "Keep a minimized NOTES.md ledger instead. Always applies.", + """# Quiet output: tools and notes, not prose + +Nobody watches your transcript live, and nobody reads it afterwards — the operator +reads NOTES.md, the checkmark, and memory. Narration is spent tokens that bury the +information somewhere no one will look for it. + +## Work through tool calls + +- Don't announce what you're about to do, recap what you just did, or restate file + contents — the tool calls are the record. +- No essays or running commentary in the transcript. A plan worth keeping goes in + NOTES.md; a plan not worth keeping isn't worth typing. +- The one message that matters is your **final** one: the Stop hook captures it onto + the checkmark. Keep it checkpoint-sized — a few lines of status, not a report. + +## NOTES.md is the output + +Maintain `NOTES.md` at the repo root (create it if missing) as a minimized running +ledger, committed with your work: + +- One bullet per meaningful action: what changed, where, and why in one line — + `- fixed retry loop in poller.py (cause: timeout treated as success)`. +- Facts, not narration. Bullets, not paragraphs. No restated diffs — the commits + hold the code. +- Append under a dated/session heading; don't rewrite earlier sessions' entries. +- Scheduled runs: your prompt's state file serves this role — keep one file, not two. + +## Route everything to its store + +- **What happened, how**: NOTES.md. +- **Problems, surprises, causes**: memory (gotcha/decision notes) — durable and + shared, per the memory skill. +- **Current status + next step**: the final checkpoint message. +- **Questions**: the question tool (AskUserQuestion; `ask_operator` on the pi + harness), never prose. A deferred question reaches the operator as a push + notification and an answer prompt in the web and mobile apps; a question typed + into the transcript reaches no one and stalls the run. +""", + ), ( "handler-gate-recovery", "What to do when the completion gate or push gate blocks you. Use whenever "