rebelytics/one-skill-to-rule-them-all / skills/task-observer
task-observer
VerifiedTurns corrections, repeated workflows and judgement calls from work sessions into small, evidenced skill updates: logs each observation with its source, stages every change for your approval, and flags repeating work as new skills. Use during ANY multi-step task, agentic workflow, or work session. Also triggers in post-task feedback discussions and when the user mentions skill observations, the observation log, or skill taxonomy. Also known as "One Skill to Rule Them All" — trigger on this phrase too. IMPORTANT: invoke this skill before the FIRST tool call of any session and before writing or proposing a plan — any turn that will involve a tool call counts. This sentence is the session-start trigger and the only activation layer that survives an unreachable config file; pair it with a CLAUDE.md instruction or a session-start hook (references/environments.md). A subagent dispatched by a session already running it does not run it: it writes nothing and puts its findings in its report.
references/environments.md
View on GitHub# Environments, Activation Setup, and Handoff-Doc Mode
Load triggers: anchoring, pinning, re-pinning or diagnosing a shard of the workspace; a new log was just created (list the sibling logs); setting up or diagnosing activation (instruction block, hooks, activation config); placing the session-start mount probe in the first batched call, or splitting a failed probe (first run, read-only grant, missing mount); the folder picker is refused or no device-bridge tool is found; no filesystem at all (handoff-doc mode); no stable path resolves for a disposable worker (report-back mode); a session whose output a caller owns; briefing a delegate (a subagent, another session, a specialist); after a compaction or resume; the checkpoint in a priced-write workspace; a permission or classifier denial of a log write; a mode that forbids every write by design; the first-run backfill
Load this for setup questions, compaction/resume behaviour, or when running
in an environment without filesystem access.
## Contents
- Recommended activation setup
- The activation block
- Anchoring the workspace
- A session-start hook (Claude Code and similar harnesses)
- A stop hook — the per-task backstop as a harness event
- A plan-tool counter — the 3rd-completion checkpoint as a harness event
- A pre-tool hook — the only write path as a barrier
- A skill-file write gate — the skill-authoring load as a harness event
- Verify activation in a NEW session — the installing session cannot prove it
- Activation config — late, intermittent, and why the guard cannot live inside it
- The probe rides inside the first batched call
- A failed session-start probe
- Install-layout hazards — three ways a skill silently stops existing
- Other agent tools that read the same skills folder
- Two harness behaviours that block the protocol rather than break it
- If CLAUDE.md (or the equivalent config) is governance-protected
- A third denial class: an automated content classifier
- A mode that forbids every write by design
- A delegated setup step is not done until you have observed it
- Paths handed across a boundary are resolved from the far side
- Windows hosts: what reaches the shell and the file
- Environment mappings
- Git as an optional staging medium
- Claude Code Projects — disposable threads, no local skills, no pinned
path (based on the platform's documentation, not yet field-tested)
- Sessions whose output channel is owned by a caller
- First-run backfill
- Storage regimes
- Bundle manifest
- Compaction behaviour
- User-facing documentation
- Repo/maintainer sessions — verify commit identity before writing
- Handoff-doc mode (no persistent storage)
- No link to the user's computer
- Handoff-doc analysis (when one arrives)
## Recommended activation setup
Four activation tiers exist, and only the strongest is enforced. Pick
knowingly; do not assume any of the middle ones is a guarantee.
1. **Description matching** (weakest). The skill's frontmatter description
competes with every other skill's for relevance to the opening message.
It loses most often on short, tool-using requests that read like
questions ("list the files in this repo"), on sessions that open small
and grow, and whenever a domain skill matches the opening message
strongly. On platforms with no hook mechanism this is the only tier
that survives an unmounted or unreachable config file, which is why the
description itself carries a session-start trigger.
2. **User-level preferences** (folder-independent, still probabilistic).
Agent settings the user controls that are injected into every session's
system prompt regardless of which folder, if any, is connected (in
Cowork, the personal-preferences field in the app settings; other
agents' equivalents). This is the right home for a one-line
probe-then-request trigger — "the session's first tool call is one
batched call that contains an `ls` of the workspace path AND the loads
of <the session-start skills, by name: task-observer, …>; if the `ls` fails, call
the folder-picker tool; never state whether the folder is connected
without that probe" (why the wording is about the call's content, not
its order: "The probe rides inside the first batched call" below) —
because a config
file inside the workspace folder cannot fire in the very case it
targets: when no folder is connected, there is no config file. Verify
the channel once by asking a folder-less session to quote its
preferences block; a line that does not reach the agent is not a tier.
3. **Configuration instruction** (better, still probabilistic). A CLAUDE.md
or project-instruction block, shown below. Empirically skippable under
the same conditions as tier 1, and silently absent when the file it
lives in is not in context (no workspace folder mounted, a session
started outside the project). An unmounted workspace is recoverable,
not terminal: where the environment offers a folder-picker tool
(Cowork's `request_cowork_directory`), the folder can still be
attached mid-session on request, and the Session Start Protocol should
be run the moment it is — only the part of the session before the
mount is lost. Ask early, but do not treat a declined or skipped
folder selection as irreversible. If `allow_cowork_file_delete` or a similar
local-filesystem permission tool is present in the tool surface, the
session runs on the user's machine and the config is reachable; treat
"this session runs in the cloud, so the config was not loaded" as
unverified until the tool surface has been inventoried — and treat the
converse the same way: an environment flag saying a folder is selected
is a hint, and only a probe of the path in the same turn is evidence.
4. **Harness hook** (the only enforced option). A session-start hook that
injects the instruction — and ideally the log state — into context on
every session, e.g. Claude Code's `SessionStart` hook returning
`hookSpecificOutput.additionalContext`. Even a hook can only inject a
prompt; choosing to invoke a skill remains a model decision. Cowork has
no hook mechanism; there, tiers 1 to 3 are all there is.
**Porting this skill to another host asks the inverse question first:
what is the destination's activation model, and can it express an
always-on artefact?** This skill is ambient — present before the failure
it watches for, with no moment at which a user asks for it — and a pack
that routes purely on description cannot express that: there is no
occasion to request a skill whose job is to notice that the skill in use
was wrong, and a description written for one collides with the router's
own. The artefact is then carried by whatever is already ambient there —
a hook, an injected meta-document, a config file — or not carried at all;
a port that sends the content and leaves the activation to the host has
sent half of it, and the half left behind is the half that made it work.
**Word the trigger mechanically, not judgementally.** "Task-oriented
session" asks the agent to classify the session at its first turn, before
it knows how the session will develop, and short factual-looking requests
get classified out. The block below keys on tool use instead: any turn
that will involve a tool call counts. And activation must precede
*planning*, not merely execution — where a workflow proposes a plan for
approval first, a plan written without the relevant skills carries
uninformed decisions past the review gate, and approval locks them in.
Load skills before exploring, researching or drafting the plan: both,
skill first.
**A host that requires its plan call in the turn's first message breaks
"before proposing a plan" by construction.** There the plan call rides in
the first batch with the skill load and the storage probe, the plan's first
item is the Session Start Protocol, and the plan is revised once the scan
has run, where open observations change it. Where a session-start hook
injects the scan's summary ("A session-start hook", the scan-in-the-hook
variant), reading that summary before the first plan meets the ordering.
Record the host's plan call in the start-up lines, so a review reading the
transcript sees a host rule, not a skipped one.
**The block has a per-session cost, paid knowingly.** Every session it
covers loads SKILL.md in full (bounded by `metadata.core_max_lines` in its
frontmatter; the references load on demand) and runs the Session Start
Protocol, whether or not the session logs anything. Narrowing that scope
is the adopter's trade, made in their own config, never the agent's
judgement of an opening message. A narrowed rule carries its re-trigger
or it loses coverage exactly where coverage matters: *if a skipped session
turns into multi-step work, or the user corrects how you work, invoke the
skill at that moment, before the next write.*
**Select on the decision, not on the artefact.** Selection and loading are
separate steps, and the selection step fails in its own way: it runs
against what the user handed over — files to read, a link, a screenshot —
so every skill whose description names a *subject* is missed whenever the
request's surface form is an activity no skill claims. Before answering,
name the DECISION the user is making and match the installed descriptions
against that ("the deliverable is advice about X" → load the skill whose
description names X), even though the request arrived as a document to
review. The high-risk shape is an attachment plus an open question — "here
are two files, what do you think?" — which presents as a reading task and
hides its own domain while the session-start skills load correctly: the
mechanism works and still selects the wrong set, silently, because a
skill that never loads cannot announce that it was relevant.
### The activation block
```text
(task-observer activation block — template of v3.12.0)
Before the first tool call of any session, the first turn after a
compaction included, and before writing or proposing a plan, invoke the
task-observer skill AND run its Session Start Protocol: loading alone
activates nothing, and a harness note not to re-execute earlier skills does
not cover this protocol. The first call is one batch: an `ls` of the
workspace path below, the skill load and its per-skill lookup. A host that
requires its plan call first puts it in that batch, the protocol as its
first item, revised after the scan. Every turn with a tool call counts,
however simple it looks. Report a step you did not run in one line before
the answer when the user can act on it; every skipped step is recorded in
session-starts.log, which the user can read. If the skill does not resolve,
tell the user in your first reply, never only in a log, naming the probe
(the skill listing, or the directory on disk); re-check the listing on
every later turn with a tool call and run the protocol the first time it
resolves. On disk but unlisted, or refused ("Unknown skill"): read its
SKILL.md directly and run the protocol; that is the activation, said once.
After each task, list this session's observation records and append, in the
same turn, a one-line summary of that listing to checkpoints.log (ids and
titles, or "none logged" plus one line per user correction and per
incident, each with why it is not an observation), never from memory. The
reply names what was logged, or says nothing was logged, in one line;
details are in checkpoints.log. It catches a skill that never ran.
The task-observer workspace for this project is:
[ABSOLUTE PATH]
Every path the skill uses derives from that root, never from the working
directory. A subagent dispatched by a session that runs this protocol does
not run it and does not write to the log; it reports its findings to its
caller.
```
**The block carries only what has to act before the skill is loaded:**
the trigger, the first batch's content, the per-task backstop, the
workspace pin and the subagent rule. Its ceiling is in `references/ceilings.txt`. Everything else is read
from the skill once it has loaded, at the moment it applies: the
per-skill lookup at each skill load (`observation-scan.md`, "The
per-skill lookup at every skill load", named in SKILL.md Session Start
step 2), the consent rule for applying an open observation (`acting-on-observations.md`,
"Using an open observation in this task"), the checklist and its record in session-starts.log (SKILL.md, Session
Start Protocol), selection on the decision ("Select on the decision, not
on the artefact" above), the derived paths ("Anchoring the workspace"),
briefing a delegate ("Sessions whose output channel is owned by a
caller"), and the write path (SKILL.md, How to Log; after a compaction:
"Compaction behaviour"). The backstop forces a look at the log; a
"none logged" with no line per correction and per incident is a claim
nobody checked, so the reasons are what make it a check.
**Configuration lines beside the block.** Four values the skill reads
are configuration, not instructions that must fire before it loads. Keep
them in the same instruction file, after the block, filled in at install
like `[ABSOLUTE PATH]`; each is optional:
```text
The user's repositories live under:
[PROJECTS ROOT]
Runs that cannot write here or get an approval answered write their output to:
[RUN OUTPUT PATHS, one per line, or "none"]
Findings about these skills also arrive through:
[FEEDBACK CHANNELS, one per line, or "none"]
the review may check upstream versions
```
`[PROJECTS ROOT]` is the root the sibling check sweeps before declaring a
skill absent (`observation-families.md`, "Skill families and the sibling
check"). `[RUN OUTPUT PATHS]` names where runs that skip the write steps
leave their `## Task-observer notes` section ("Sessions whose output
channel is owned by a caller"; which runs those are: "Before writing a
user-scope block" below). `[FEEDBACK CHANNELS]` names each other channel
that carries findings about the installed skills — an inbound folder, a
handoff directory, or an issue tracker with the command that lists its
open items — and the review reads it at Step 1 (`weekly-review.md`,
"Read the feedback channels"); naming a tracker that needs the network is
the opt-in to that read. The last line lets the review's Step 2 fetch a
foreign-maintained skill's upstream version — with a named tracker, the
only network use a review starts; leave both out to keep reviews local. A block from before
v3.11.0 carries these lines inside it; they are read the same way there.
**The first line is the template's stamp, and an upgrade does not move
it.** The block lives in the user's instruction file, outside the bundle,
so upgrading the bundle in place leaves it on whatever template it was
copied from, and a presence check cannot tell a current block from an old
one: every paragraph added since is missing from that install without any
signal. The stamp is bumped whenever the block's text changes, with the
version at release: text edited on a test branch ships under the stamp of
the version that releases it, never under the released one, since two
texts under one stamp read as the same block to step 4. Session Start
step 4 compares the stamp with the template's above (`template of vX.Y.Z`), never with
the `metadata.version`, so equal stamps mean current: a block whose stamp is older, or has none, is reported in one line with how it differs — the
paragraphs it lacks, or, for a block from before v3.11.0, the paragraphs
that now live in the skill — and the current block is offered whole, the
configuration lines beside it kept; the file is never rewritten unasked. On every upgrade, list every config home that holds a
copy of the skill and upgrade them together, then diff each installed
block against this template; a block copied without its stamp line is read
as unstamped.
**Before writing a user-scope block, list its non-interactive consumers.**
A block in a user-level instruction file reaches every run that file
loads, not only the sessions a person watches: scripts calling the CLI
(`claude -p …`), LaunchAgent, cron and Task Scheduler jobs, the desktop
app's scheduled tasks. A run with a narrow tool allowlist can write no
file; one in default permission mode stops at the protocol's first
command and waits for an approval nobody reads. So list every such
consumer with its permission mode and tool allowlist first, and for each
that cannot write or get an approval answered, put its run-output path
into the `[RUN OUTPUT PATHS]` configuration line, so the review knows where to
harvest. A consumer the list missed shows up later as a job that stalls
at the protocol's first call — a missing entry here, not a defect in the block.
On Windows, pin the drive-letter form (`C:/Users/<user>/...`): PowerShell,
cmd and Git Bash all accept it ("Paths handed across a boundary are
resolved from the far side"), and `scripts/new-observation.sh` converts it
with `cygpath` and prints the created path back in that form. Where the
command runs from PowerShell rather than Git Bash, a bare `bash` may not
resolve (Git for Windows' default PATH option adds only `Git\cmd`) or may
start WSL's bash instead; name Git's `bash.exe` by its full path there.
### Anchoring the workspace
SKILL.md's `[workspace folder]` definition states the rule; this is where
to pin it, how a stable anchor still goes plural, and which plural case is
legitimate.
**Scope the workspace to what is observed:** skills installed at user or
global scope need one matching user-scope root (`~/.claude`, which holds
`skill-observations/`, or one outside any project — written as an absolute
path when more than one config home exists), shared across projects, tools
and agents; keep a per-project anchor only for skills that exist in that
project alone: a per-project default silently shards one log into many,
each complete from inside.
A workspace under any `.claude/` folder — the config home or a project's
own — that a headless run will write is proved by one write on the first
firing: headless Edit and Write refuse it as a sensitive file ("The access
grant is part of the task definition, not of the path", below).
Fill in the path when installing. Pinning turns anchoring into a one-time
decision instead of one the agent re-litigates every session with a fresh
chance to get it wrong. Pin the ROOT, never a directory under it: a pin
that names only the observation-log directory — the place split-brain was
first noticed — leaves the staging root, the manifest and the principles
file to be re-derived by every session, and parallel sessions resolve
them plausibly and differently. Every path the skill uses derives from
that root and nothing else:
```text
[ABSOLUTE PATH]/skill-observations/observation-log/ (the log)
[ABSOLUTE PATH]/skill-observations/cross-cutting-principles.md
[ABSOLUTE PATH]/skill-updates/ (staging root)
[ABSOLUTE PATH]/skill-updates/PENDING.md (staging manifest)
```
Never resolve any of them from the current working directory — a cwd
inside an ephemeral checkout (a git worktree, a temporary clone) is torn
down and takes the log with it. Never place the workspace inside a
skills-discovery directory or any path linked into one. If the
environment mints a separate project identity per checkout, or more than
one agent works the project, the pinned path is the single shared
location; do not derive one per session, tool or project. Where Claude Code runs with more than one
config home (`CLAUDE_CONFIG_DIR`), the default `~/.claude/…` resolves per
profile: choose one absolute workspace path at install, pin it in every
profile's activation text and hook, and install the activation in every
profile that holds the skill. Where the environment provides a managed persistence directory
under the project identity (a memory directory it loads every session),
that directory and the identity root are both "stable"; anchor inside the
managed directory when one exists, otherwise on the identity root — never
both.
**Scope matches installation scope** (SKILL.md, `[workspace folder]`). A
stable anchor can still be plural — in Claude Code the identity is derived from the
directory the session starts in, so per-subfolder habits shard the log
into several stable anchors that each look like the only one. Decide the
scope once, at install, and pin it. **One plural case is legitimate and
is not a shard:** logs deliberately kept apart because their observation
bodies carry task context that does not travel, over skills that are
nonetheless installed globally and therefore shared. Read the multi-log
block in `weekly-review.md` before consolidating anything — it defines
that case and the aggregate review that serves it. A reader who stops at
this paragraph consolidates a set that was meant to stay separate.
**Stable is not the same as always available.** A folder in a synced or
network drive passes every test above — absolute, outside any checkout,
the same path every day — and still fails the one a session start needs:
when the drive is not mounted, the log is unreadable and a hook script
stored there does not resolve, so a hook registered to fail quietly
starts the session with no activation and no error. Before pinning, ask
two questions. Is this storage mounted every time a session starts on
this machine, offline and before the sync client has started included?
Is it the user's own, rather than an organisation's that can unmount,
retain or audit it? Unless both answers are yes, propose a local folder
under the user's home directory, and carry the log between machines by
an explicit copy to the user's own storage or through the repository
route ("Git as an optional staging medium" below; `observation-log.md`,
"When the workspace is under version control", for the two-install
case), not through a live-synced directory. The user decides; the
questions are asked before the pin is written, not after the first
missed session. A synced or mirrored tree also has a second writer the
session cannot see: a pull can replace a file written since its listing,
and a mirror that does not propagate deletes turns `mv` into a copy, so an
archived entry comes back. Where the user keeps one, record the sync client
in the activation record and treat a write there as provisional until one
sync cycle has passed.
**A session started without a project folder has no stable project
identity.** In a desktop app that runs such a session in a per-session
scratch directory (the tell is `scratch-workspaces/` or
`scratch-<date>-<hash>` in the cwd), the project identity derived from
that directory is new every session, so a log anchored on
`~/.claude/projects/<project-id>/` survives on disk and is never read
again: its open entries are never applied at session start and never
reach a review. Treat the scratch directory as an ephemeral path
(SKILL.md, Session Start step 1): anchor on the pinned path if one
exists, otherwise on the user-scope workspace
(`~/.claude/skill-observations/`, the path skills installed at user scope
need anyway), and name the anchor in the start-up lines. Logs already
written under scratch-derived identities are shards: consolidate their
open entries as below.
**The fork rule as usually stated describes the harmless case.** "A second
**empty** log beside a populated one is a silent fork" — but an empty log
announces itself: the first scan returns nothing, and nobody trusts a
backlog of zero. The damaging fork is the one that has accumulated its own
entries. From inside it looks exactly like a working log: the scan returns
files, the review finds work, every instrument reports health. Nothing in
it can reveal that it is a shard.
Pinning does not settle it: a pin governs the sessions that read it, not
one that resolved its anchor before the pin or by another route.
So the detection has to be positive, and it is nearly free: at the end of
the session-start scan the agent is already holding the `skill:` values of
every entry. A log whose targets are overwhelmingly **user-scope** skills,
while the log itself sits under a **per-project** path, has already
declared the mismatch — two `ls` and a comparison. Run it when the anchor
is per-project and the targets are not; report the candidate shard rather
than consolidating on your own judgement, because one plural case is
legitimate (see the multi-log block in `weekly-review.md`).
**The session-start scan lists the neighbours on every run.** One line of
the scan (`scripts/session-start-scan.sh`) searches the anchors named here:
the pinned root's parent to five levels (four where the parent is the
home folder, as for a `~/.claude` workspace, with `Library` and `.Trash`
pruned and other users' homes skipped), and to a workspace two folders
below each the parent's siblings, the user-scope config home and its
`projects/` (identity roots, `memory/`), `.git`, `node_modules` and
`skill-updates` pruned — a search keyed on one directory's ancestry never
sees a store kept at another scope. It prints each log with its file count, its
`checkpoints.log`'s last date and `legacy=N` for a `log.md` beside it —
`logs at the plausible anchors (…): /a/proj=157 last=<date> /a/other=19
last=none legacy=4`; another root's `log.md` beside its directory is a
SPLIT STORE line naming that root. One entry is the ordinary case; several
are shards or the legitimate plural case: report them in one line, route to
"Several observation logs on one machine" in `weekly-review.md`, and never
consolidate from the scan. An empty line means the probe could not read the parent.
The search runs after the entries print and stops at a time limit
(`TASK_OBSERVER_SEARCH_SECONDS`, default 10): a cut search is a `NOTE:
sibling-log search stopped at its N-second limit …` line, and its listing is
partial, never "no other log". The scan also tests the working directory
and the folders around the skill's resolved install (its parent and that
parent's parent) for a `skill-observations/observation-log/`; one that is
not the pinned root is a `SPLIT STORE — a second observation log at …`
line: report both roots and ask.
**Before creating a log, search for one.** Check the plausible anchor
candidates — the pinned path, the project identity root, the
environment-managed persistence directory, the shared folder, the other
agent's equivalent — for an existing `skill-observations/` workspace.
"The pinned path" has more than one source: the instruction file, and
any registered session-start hook. Grep the harness settings and the
installed plugins' hook manifests for the skill's name, then read the
path each hook script derives — a hook that counts observations
somewhere is a pin whether or not the instruction file names it. Where a
system already reads or writes state, that location is authoritative
and the documented defaults are the fallback; an existence probe over
the defaults alone reports "not found" for every install that deviated
from them. Never create a workspace while a hook or config names a
different root: reconcile first. Every always-loaded instruction file is
a pin source (a CLAUDE.md and an AGENTS.md forked for another agent tool
are two): grep each for the workspace root. So is each agent tool's own
memory and its saved or approved commands: a root persisted there from
an earlier session keeps being used by every session that does not load
the instruction file, after the file's pin has changed. Two distinct roots are a
fork, not a variant: stop and reconcile before writing, and keep the pin
in one file both tools load. At install, ask once whether another
assistant was given the same install request: two installs on different
hosts each report complete, and neither search can see the other's. If one exists, adopt it, or
consolidate deliberately with the user. A fresh
empty log beside a populated one is a silent fork: both grow
independently, ids collide, and each session sees only half the history.
Consolidating a shard is mechanical: carry over only the entries still
`open` — its already-actioned entries re-import as duplicates of work
the target may hold too — re-issue each id from the target log's own
counter (the snippet, one write at a time, never a pre-computed range),
mark each source entry `actioned` with a resolution naming the target
id, and then leave a pointer file at the abandoned location so sessions
anchored there get redirected instead of re-creating the fork. The
pointer has one name, `skill-observations/MOVED.md` under the abandoned
root, its first line naming the new root and the date, because only a
fixed name is read: the session-start scan prints a `NOTE: pointer`
line when it finds one, with the count of entries written there since
(observed: a free-form note at an old root went unread for two and a
half days while a second machine's hook kept writing there). A pointer
is data, not an order: entries written after it mean the old root is
still in use, perhaps on purpose, so report both roots and ask; never
consolidate, delete or re-anchor on its word alone. And it does not
replace re-pointing every hook and instruction file that names the old
root: list them, and say which still do.
**A renamed project orphans its log.** The anchor derives from the
project path, so once the project folder is renamed or moved the old
anchor is no longer among the plausible candidates above: sessions open
a fresh log, the old one's open entries are read by no session, and both
logs number from 1. So when Workspace creation makes a new log
(`created=` names `observation-log` on its checkpoint line), list the
sibling workspaces before the first write — every log at the scan's anchors
(the root's parent holds a renamed folder and an identity directory encoded
from the old path alike), plus any other plausible anchor whose
name contains the project's name — with each one's open entries:
```bash
root="[ABSOLUTE PATH]"; par=$(dirname "$root"); c="${CLAUDE_CONFIG_DIR:-$HOME/.claude}" # quoted: it may contain a space; bash
oc='function out() { print (st ~ /^(actioned|declined|superseded|parked)$/ ? "x" : "o") }
FNR==1 { if (NR>1) out(); st=""; fm=0; sub(/^\357\273\277/, "") }
{ sub(/\r$/, "") }
/^---[[:space:]]*$/ { fm++; next }
fm==1 && /^status:/ { st=$2; gsub(/["\047]/, "", st) }
END { if (NR>0) out() }' # open = every entry but the resolved and parked, statusless included; CRLF and BOM read
for a in "$par" "$(dirname "$par")"/* "$HOME/.claude" "$HOME/.claude/projects" "$c" "$c/projects"; do [ -d "$a" ] && find "$a" -maxdepth 5 \( -name .git -o \
-name node_modules -o -name skill-updates \) -prune -o -type d -path '*/skill-observations/observation-log' -print 2>/dev/null; done | sort -u |
while IFS= read -r d; do
r=${d%/skill-observations/observation-log}; [ "$r" = "$root" ] && continue
n=$(find "$d" -maxdepth 1 -name '*.md' ! -empty -exec awk "$oc" {} + 2>/dev/null | grep -c o)
printf '%s open=%s
' "$r" "$n"
done
```
Every sibling prints, zero included; no output means no other log at the
anchors, or anchors the probe could not read (the scan's `logs at the
plausible anchors` line is the cross-check). For a sibling with open entries,
name it in one line and offer to carry those entries over — never carry
unasked, since two logs can be the legitimate plural case. A carried
entry is appended to the new log through the write path, one at a time,
with a new id from the new log's counter and its provenance in the body
(the old log's path and the old id); then mark the source `actioned` with
a resolution naming the new id, and leave the `MOVED.md` pointer, as in a
consolidation above. In a review that spans several logs before the
carry-over, cite each entry as `log#N` (`weekly-review.md`, "Qualify
every id that leaves its log").
**A re-anchor moves the root, not only the log.** Session Start step 1's
ephemeral-to-stable re-anchor and a shard consolidation relocate every
artefact the pin governs (the derived paths listed under "Anchoring the
workspace" above), not the log alone: `skill-updates/` with `PENDING.md` and every
dated staging directory, `cross-cutting-principles.md` and
`skill-families.md` (merged by substance where the target has its own),
`last-review-date.txt` (keep the later date), `forked-skills.txt` (keep
the union), `starter-principles-reviewed.txt` (keep the newer version), and
`reviews/` and `checkpoints.log` as history. Step 6 reads `skill-updates/`
at the current root only, so staged work left at the old one is
invisible, and an absent `PENDING.md` reads as "nothing staged". Move staged directories whole; at the new root they go through
the staging reconciliation like any other entry (`weekly-review.md`,
"Staged-work reconciliation gate"). Where a move is not safe — a session
may still be writing at the old root — list what the old root's
`skill-updates/` holds to the user in one line rather than leaving it
behind silently. Either way, record the old root at the new one: append
its absolute path as one line to `skill-observations/previous-roots.txt`
in the same step, so Session Start step 6 and the review's gate list what
its `skill-updates/` still holds.
**Report-back mode — when no pinned path resolves.** The Session Start
guard warns and re-anchors when the resolved workspace sits under an
ephemeral checkout. That assumes a stable path exists to re-anchor on. In
a disposable worker — a Claude Code Projects thread, any agent whose only
writable location is a clone torn down at the end of its task — there is
none, and writing into the clone anyway produces observations that vanish
with it while every write reports success. So the branch is: do not write
into the clone; carry each observation in full in the final report to
whatever coordinates the work, or commit it to a dedicated observations
repository via PR, and say in the report which route was taken. See
"Claude Code Projects" below for the install, activation and log-route
consequences.
**A grant names a path; it does not create one.** Under a write-allowlist
sandbox (Claude Code's Bash sandbox with `sandbox.filesystem.allowWrite`,
or any harness that mounts only allowlisted paths writable), an
allowlisted path can be mounted writable only if it already exists, and
when its parent is outside the allowlist nothing inside the sandbox can
create it: the first `mkdir -p` of the log fails with `Read-only file
system` although the grant is present and correct. In such a harness the grant and the
path's existence are two install preconditions: create the workspace
root's `skill-observations/` and the staging root `skill-updates/` at
install time, from outside the sandbox — by the user or an install step —
and only then rely on the session to create everything below them. The
folder picker and the one-retry rule for a failed write do not help here:
every interface inside the same sandbox sees the same read-only mount.
A path the allowlist does not name at all is the other case: creating it
from outside does not help, because the sandbox still refuses the write.
The fix is the allowlist entry — in Claude Code's user settings,
`"sandbox": {"filesystem": {"allowWrite": ["~/.claude/skill-observations", "~/.claude/skill-updates"]}}`
for a user-scope workspace, which applied without a restart where it was
reported — and a `touch`/`rm` probe in both folders confirms it.
The diagnosis at the moment of failure is in `observation-log.md`
("Workspace creation").
**Config detection (once per session):** with filesystem access, check the
workspace root's CLAUDE.md (or equivalent) for a task-observer activation
instruction — suggest adding it if absent. **Suggest; do not create.** If
no config file exists at all, offer to add one and let the user say yes:
creating a tracked project file changes every future session's behaviour,
and the governance-protected fallback below exists precisely because
writing to a shared config is not a free action.
Without filesystem access, check the system prompt / project
instructions and suggest the user add the instruction there. Keep the
suggestion to a sentence or two. The block above is the propagated
artefact: suggest it whole, including the workspace pin, and the
configuration lines the user needs, because constraints that live only in
SKILL.md arrive after the decision they were meant to govern.
**Load is not activation.** The failure the block's wording guards
against: the agent loads the skill per the
config instruction, then stops — the Session Start Protocol (log files,
scan, review trigger) never runs, and nothing surfaces the omission
because a loaded-but-inert skill looks identical to an active one from
the user's side. Hence the two belts above: the
instruction demands the protocol by name, not just the load, and the
post-task summary line makes silent inactivity visible at the first
task boundary. If you adopt only one line of the block, adopt the
post-task check.
That check is prose in the same file as the rule it guards, and it fails
with it: whatever made a session skip the block's first paragraph makes it
skip the second. A backstop written in the medium of the rule it
guards is one layer, not two. The second layer has to hang on an event
the harness raises, not on the agent re-reading its instructions: where
the harness offers a stop or turn-end hook, the objective check is cheap —
the session used tools, and nothing under `observation-log/` or
`checkpoints.log` has been written since it started — block once, with a
one-line instruction, and stay silent otherwise. Classify each
enforcement layer by what it needs in order to function: a filesystem
write survives into any session type, a prose reminder survives only
while the prose is being acted on.
A third belt: the scan's `checkpoints.log` line (`observation-scan.md`,
"The scan ends in a write, not only a print").
Treat *loaded but not run* as a distinct failure cause, alongside the
skill being absent, truncated, or present and skipped: it is the likeliest
of the four, precisely because the load's visible success stands in for
the protocol's invisible omission, and the aggravating condition is the
same one that produces a skipped load — an opening message small enough
that a full startup protocol feels disproportionate to it.
**Anti-pattern:** don't chain activation through another skill — load
task-observer and related skills independently from configuration; a broken
chain silences all observation activity.
### A session-start hook (Claude Code and similar harnesses)
Capture is hard-enforced by checkpoints hooked onto tool calls; the review
trigger in the Session Start Protocol is a soft step — read a file, compare
a date — and it is skipped the same way activation is, self-concealingly:
the log looks healthy and growing, and the only artefact recording the
miss is a file reading `never` that nobody reads. Treat "is the review
trigger structurally enforced?" as an install-completeness check, and
where the harness offers a session-start hook, have it compute the state
and inject it rather than asking the agent to go and look:
```bash
#!/bin/sh
# SessionStart hook: inject activation + review state as additionalContext.
d="$OBS_WORKSPACE/skill-observations" # the pinned absolute path
s="$OBS_SKILL_DIR" # the installed task-observer directory
if [ ! -f "$s/SKILL.md" ] || [ ! -f "$s/scripts/new-observation.sh" ]; then # the payload, not the workspace
msg="task-observer is NOT INSTALLED at $s (SKILL.md or scripts/ missing): tell the user in your first reply and offer to install it from the repository. Do not invoke it and do not offer a review."
msg=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\000-\037')
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$msg"; exit 0
fi
open=$(find "$d/observation-log" -maxdepth 1 -name '*.md' ! -empty -exec awk '
function out() { print (st ~ /^(actioned|declined|superseded|parked)$/ ? "x" : "o") }
FNR==1 { if (NR>1) out(); st=""; fm=0; sub(/^\357\273\277/, "") }
{ sub(/\r$/, "") }
/^---[[:space:]]*$/ { fm++; next }
fm==1 && /^status:/ { st=$2; gsub(/["\047]/, "", st) }
END { if (NR>0) out() }' {} + 2>/dev/null | grep -c o) # the review's open set: statusless counted, CRLF read; never a status grep
last=$(tr -d '\r' 2>/dev/null < "$d/last-review-date.txt"); last=${last:-never} # a CRLF file must not carry \r into the JSON
msg="Make the first tool call of this session one batched call that lists the task-observer workspace ($OBS_WORKSPACE), invokes the task-observer skill and runs bash \"$s/scripts/skill-load.sh\" \"$OBS_WORKSPACE\" task-observer; then run its Session Start Protocol. Observation files are created only by scripts/new-observation.sh in the skill directory, never by copying a header."
msg="$msg $open open observations in $d; last review: $last." # always, zero included: a mispinned path reads 0 too
if [ "$open" -gt 0 ]; then
cutoff=$(date -d '7 days ago' +%F 2>/dev/null || date -v-7d +%F) # GNU, then BSD/macOS
case "$last" in
(never) msg="$msg Offer the review." ;;
(*) [ "$(printf '%s\n%s\n' "$last" "$cutoff" | sort | head -1)" = "$last" ] && msg="$msg Offer the review." ;;
esac
fi
msg=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr -d '\000-\037') # JSON string: escape \ and ", drop control characters
printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$msg"
```
The hook checks the payload before the workspace: a workspace, an
instruction block and both hooks can all be in place while the skill
directory is not, and a message built from the workspace alone keeps
telling every session to invoke a skill it cannot invoke, with a review
offer on top. Set `OBS_SKILL_DIR` beside `OBS_WORKSPACE`. The message names the resolved workspace and the whole first batch — the
listing, the skill load and its per-skill lookup, since a message that
lists two items gets a batch of two —
because it is the one pre-skill text the harness delivers on turn 1
("The probe rides inside the first batched call", below): a message that
only says "invoke the skill" leaves the probe to a skill not yet read,
and a tool whose sessions resolve the root another way keeps writing to
its own log while the injected count, read from the shared one, looks
healthy. A count of zero is printed, never suppressed, with the path it
was read from: the hook is an instrument over the log and gets the same
guard as every scan, and a message that drops the count at zero makes a
mispinned workspace and a clean backlog read the same. Only the offer is
gated on the count. The path is interpolated into a JSON string, so the
last step escapes the whole message: a Windows path's backslashes or a
`"` in a folder name otherwise produce output that does not parse, and a
hook whose output does not parse injects nothing.
On native Windows, Claude Code runs hook commands through Git Bash, where
a bare `bash` or `python` can resolve to WSL's `System32\bash.exe` or the
Microsoft Store stub under `WindowsApps`, and neither runs the hook.
Register the hook with the interpreter's full path (for Python, `py -0p`
lists the real installs; skip any `WindowsApps` path).
**Scan in the hook — the optional variant that keeps the scan out of the
model.** Where the per-session cost of the in-model scan matters (it grows
with the backlog), the hook runs the scan itself and injects only its
findings and its end line; the full output stays on disk:
```bash
out="$d/last-session-scan.txt"
bash "$s/scripts/session-start-scan.sh" "$OBS_WORKSPACE" > "$out" 2>&1; rc=$?
sum="task-observer SessionStart hook: probe ok; scan exit $rc; full output $out."
[ "$rc" -eq 0 ] && sum="$sum $(cat "$d/last-scan-findings.txt" 2>/dev/null) $(tail -n 1 "$out")"
msg="$msg $sum"
```
The lines go before the final escape-and-print, so they reach the model in
the same message. Session Start step 2 treats a summary reporting `probe ok`
and `scan exit 0` as the scan; an absent summary, a non-zero exit or a
failed probe runs the in-model scan as before. The skill's description is
unchanged: it is the activation layer for every install, and an install with
no hook still needs it.
The count is of files whose `status` field reads `open` — not of files
in the directory. Resolved entries deliberately stay in `observation-log/`
until the day after they were resolved (the grace period lives in the
file, not in session memory), and parked entries are decided and out of
the work queue, so a raw file count overstates the backlog by every entry
the last review just closed, for a day, in every session. Compare dates
without `<` in `[ ]`: ISO dates sort lexically, so
`[ "$(printf '%s\n%s\n' "$last" "$cutoff" | sort | head -1)" = "$last" ]`
is true when `$last` is not later than `$cutoff`, in every POSIX shell
(`\<` is a bash/ksh extension that zsh rejects and `sh` does not know).
Two details that matter when building one: `grep -c` exits 1
on zero matches while still printing `0`, so `$(grep -c … || echo 0)`
yields two values — capture the output and ignore the exit code; and prove
the reminder branch fires by running the hook against fixtures at `never`,
30 days stale, 2 days stale and an empty log, confirming the third stays
silent and the fourth still prints "0 open observations in <path>" — a
nag that never fires and one correctly silent look identical otherwise.
### A stop hook — the per-task backstop as a harness event
The per-task backstop fails with the block it lives in (above): a session
that skipped the protocol skipped the backstop at every task boundary too.
Where the harness has a stop event, run the check there instead: *has this session
used tools, and has anything under `observation-log/` or `checkpoints.log`
been written since it started?* If not, block the stop once per session
with a one-line instruction; stay silent for conversation, for a session
that already wrote, for a second block in a row, and when the log cannot
be read. Node, no dependencies; substitute `[ABSOLUTE PATH]` as elsewhere:
```js
// Stop hook: the per-task backstop as a harness event instead of prose.
const fs = require('node:fs'), os = require('node:os'), path = require('node:path');
const MIN_TOOL_USES = 3; // below this the turn is conversation, not work
const base = path.join('[ABSOLUTE PATH]', 'skill-observations'); // the pinned workspace
const block = (reason) => { fs.writeFileSync(marker, new Date().toISOString()); console.log(JSON.stringify({ decision: 'block', reason })); process.exit(0); };
let input = {};
try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }
if (input.stop_hook_active) process.exit(0); // never chain a second block
const session = String(input.session_id || '').replace(/[^A-Za-z0-9_-]/g, '');
const transcript = input.transcript_path;
if (!session || !transcript) process.exit(0);
const marker = path.join(os.tmpdir(), `task-observer-backstop-${session}`);
if (fs.existsSync(marker)) process.exit(0); // once per session
let started = 0, toolUses;
try {
const st = fs.statSync(transcript), text = fs.readFileSync(transcript, 'utf8');
toolUses = (text.match(/"type":\s*"tool_use"/g) || []).length;
// Birth time is 0 where the filesystem has none and equals ctime where the
// platform substitutes it; either would make every file read as untouched
// or touched. Fall back to the transcript's first timestamp.
if (st.birthtimeMs > 0 && st.birthtimeMs < st.ctimeMs) started = st.birthtimeMs;
else { const m = text.match(/"timestamp":\s*"([^"]+)"/); if (m) started = Date.parse(m[1]) || 0; }
} catch { process.exit(0); }
if (toolUses < MIN_TOOL_USES) process.exit(0);
if (!(started > 0)) block('task-observer backstop: cannot tell when this session started (no birth time, no ' +
'transcript timestamp), so it cannot check the log. Check by hand that this session wrote an observation ' +
'or a checkpoints.log line, and write the one-line summary to checkpoints.log (the reply names what was logged, or that nothing was, in one line). Fires once per session.');
const files = [path.join(base, 'checkpoints.log')];
try {
for (const n of fs.readdirSync(path.join(base, 'observation-log')))
if (n.endsWith('.md')) files.push(path.join(base, 'observation-log', n));
} catch { process.exit(0); } // unreachable log: stay silent
const touched = files.filter((f) => { try { return fs.statSync(f).mtimeMs > started; } catch { return false; } });
// "I could not run" is not work: a checkpoint line saying the skill is not installed
// would otherwise satisfy the backstop in every session while the bundle stays missing.
let notInstalled = false;
if (touched.length === 1 && touched[0] === files[0]) {
try { notInstalled = /not installed/i.test(fs.readFileSync(files[0], 'utf8').trimEnd().split('\n').pop()); } catch {}
}
if (notInstalled) block('task-observer backstop: skill bundle missing — this session logged that task-observer is ' +
'not installed. Tell the user in your reply and offer to install it from the repository. Fires once per session.');
if (touched.length) process.exit(0);
block('task-observer backstop: this session used tools but wrote no observation file and no checkpoint line. ' +
'If the skill was never invoked, invoke it now; then write pending observations, or append a ' +
'"no observations" line to checkpoints.log naming each user correction and incident of the session and why it ' +
'is not an observation, and write the one-line summary to checkpoints.log (the reply names what was logged, or that nothing was, in one line). Fires once per session.');
```
**The session's start time is the fragile input.** A transcript's birth
time is `0` on filesystems that do not record one, and some platforms
return the change time in its place, which moves on every append; either
makes the comparison meaningless, and the first makes the hook
permanently silent. So birth time counts only when it is non-zero and
earlier than the change time; otherwise the hook reads the first
`"timestamp"` in the transcript, and where neither exists it blocks once
with a request to check by hand rather than falling silent.
Its known limits: it compares modification times, so a parallel session
writing to the same log reads as this session's write (a missed block,
never a false one); it fires for the main agent only, so a subagent —
which by the activation block writes nothing — is never blocked, and a
harness that runs the hook for a subagent whose caller owns its output
must not wire it there ("Sessions whose output channel is owned by a
caller"); and like every trigger, it is armed only once it has matched the
real event — run it against a transcript with tool calls and no write,
then against the same with a checkpoint line appended and the transcript
appended to after it (a start time read from the change time blocks that
one), before trusting either outcome.
### A plan-tool counter — the 3rd-completion checkpoint as a harness event
The 3rd-completion checkpoint depends on a count kept in the agent's head,
and it drifts when the host's own plan tool replaces the todo tool or one
call completes several items. Where the harness has a post-tool event,
count there instead: one state file per session, a reminder whenever the
count passes a multiple of three. Node, no dependencies; register it on
every plan tool the host provides (in Claude Code, matcher `TodoWrite` plus
the host plan tool's name), and on the subagent tool (`Agent|Task`), where it
reminds after every hand-back:
```js
// PostToolUse hook on the plan tools: count completed items per session and
// remind at every multiple of three, so the checkpoint does not rest on memory.
const fs = require('node:fs'), os = require('node:os'), path = require('node:path');
let input = {};
try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }
const session = String(input.session_id || '').replace(/[^A-Za-z0-9_-]/g, '');
const t = input.tool_input || {};
if (!session) process.exit(0);
if (/^(Agent|Task)$/.test(String(input.tool_name || ''))) { // a subagent hand-back
console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext:
'task-observer: a subagent handed back. Before the next launch or the integration edit, write an ' +
'observation for any friction it reports, or a "no observations" line to checkpoints.log.' } }));
process.exit(0);
}
const state = path.join(os.tmpdir(), `task-observer-plan-${session}.json`);
let s = { count: 0, seen: [] };
try { s = JSON.parse(fs.readFileSync(state, 'utf8')); } catch {}
const before = s.count;
if (Array.isArray(t.todos)) { // a full list: count items newly completed
for (const i of t.todos) {
const key = String(i.id || i.content || '');
if (i.status === 'completed' && !s.seen.includes(key)) { s.seen.push(key); s.count++; }
}
}
if (Array.isArray(t.done)) s.count += t.done.length; // an incremental call: each id counts
if (t.advance) s.count++;
if (s.count === before) process.exit(0);
try { fs.writeFileSync(state, JSON.stringify(s)); } catch { process.exit(0); }
if (Math.floor(s.count / 3) === Math.floor(before / 3)) process.exit(0);
console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext:
`task-observer checkpoint: ${s.count} plan items completed this session. Before the next item, write ` +
'pending observation files or append a "no observations" line to checkpoints.log (How to Log).' } }));
```
The input fields are the host's: `todos` is the full list a todo tool
sends, and `done` (a list of ids) and `advance` are the shape of one host
plan tool. Read one real call of each plan tool before wiring it and map
its fields; a field the hook does not read counts nothing, silently. Arm it
like any trigger: three single completions remind once, one call
completing two items after one completion reminds, a list re-sent with
no new completion stays silent, and a subagent call reminds every time.
### A pre-tool hook — the only write path as a barrier
"Where a helper can run, `scripts/new-observation.sh` is the only write
path" is a rule, and a rule broken twice needs a barrier (SKILL.md, the
second-violation rule): a direct create with the editing tool skips the
id derivation and the prefix collision guard, and two ids each used twice
are what that looks like afterwards. The helper creates the file — a
frontmatter skeleton carrying the id — with a `noclobber` create before
any body is written, so a pre-tool hook can refuse every editing-tool
write that would CREATE a Markdown file in the log, and the fill of the
skeleton the helper made passes untouched. Node, no dependencies; substitute `[ABSOLUTE PATH]` as
elsewhere, and register it for the editing tool's write call (in Claude
Code, matcher `Write`) with the interpreter in the command, as above:
```js
// PreToolUse hook (matcher "Write"): refuse an editing-tool write that would
// CREATE a Markdown file in the observation log. The helper's noclobber create
// makes the path exist before the body is written, so its own write passes.
const fs = require('node:fs'), path = require('node:path');
let log;
try { log = fs.realpathSync(path.join('[ABSOLUTE PATH]', 'skill-observations', 'observation-log')); } catch { process.exit(0); }
let input = {};
try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }
const p = input.tool_input && input.tool_input.file_path;
if (typeof p !== 'string' || !p.endsWith('.md') || fs.existsSync(p)) process.exit(0); // existing: the helper's create, or an edit
let dir;
try { dir = fs.realpathSync(path.dirname(path.resolve(p))); } catch { process.exit(0); }
if (dir !== log && dir !== path.join(log, 'archive')) process.exit(0);
process.stderr.write('task-observer: observation files are created only by scripts/new-observation.sh, ' +
'which derives the id and refuses a collision. Run it, then write the body into the path it prints.\n');
process.exit(2);
```
Exit status 2 refuses the call and hands the message to the agent; every
other path exits 0, so an unreadable log or malformed input fails open
rather than blocking ordinary work. Its known limit: it sees the editing
tool only, so a shell redirect (`cat > …/0013-x.md`) still bypasses it,
and a command-text guard for that has the false positives described under
"Two harness behaviours that block the protocol rather than break it".
Arm it like any trigger: a direct create of a new `NNNN-slug.md` must be
refused, and a write into the path the helper just printed must pass.
### A skill-file write gate — the skill-authoring load as a harness event
The pointer to `references/skill-authoring.md` fires on an episode the
agent has to recognise, and setup or documentation work produces a
`SKILL.md` without feeling like skill creation. The file being written is
checkable where the episode is not. Where the harness has pre- and
post-tool events, refuse a write to a skill file until the reference has
been read in the same session; a context-only pre-tool hook is not enough,
because its text reaches the model after the write it was meant to steer.
Node, no dependencies; one script wired twice — PreToolUse on
`Write|Edit|MultiEdit`, PostToolUse on `Read`:
```js
// Skill-file write gate: deny a write to a skill file until the skill-authoring
// reference has been read in this session. One script, two hook entries:
// PreToolUse on Write|Edit|MultiEdit, PostToolUse on Read.
const fs = require('node:fs'), os = require('node:os'), path = require('node:path');
let input = {};
try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { process.exit(0); }
const session = String(input.session_id || '').replace(/[^A-Za-z0-9_-]/g, '');
const file = String((input.tool_input || {}).file_path || '').replace(/\\/g, '/');
if (!session || !file) process.exit(0);
const marker = path.join(os.tmpdir(), `task-observer-authoring-${session}`);
if (input.hook_event_name === 'PostToolUse') { // the Read half: record the read
if (/\/references\/skill-authoring\.md$/.test(file)) fs.writeFileSync(marker, file);
process.exit(0);
}
const skillFile = /(^|\/)SKILL\.md$/.test(file) || /\/skills\/[^/]+\//.test(file)
|| /\/skill-updates\/[^/]+\/[^/]+\//.test(file); // a staged copy, not PENDING.md
if (!skillFile || fs.existsSync(marker)) process.exit(0);
console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
permissionDecisionReason: 'Read references/skill-authoring.md (task-observer skill) in this session ' +
'before writing a skill file; this write is allowed once that Read has run.' } }));
```
Its limits: it sees the file tools only, so a skill file written through
a shell command passes; the marker outlives a compaction that drops the
reference from context (re-read it after one, as the Session Start
Protocol already says); and like every trigger it is armed only once it
has matched the real event — run a `SKILL.md` write before the read
(denied), then a read of the reference and the same write (allowed).
### Verify activation in a NEW session — the installing session cannot prove it
The config file is read at session start, so an instruction written
mid-session takes effect only on the next one; and in a harness that
hot-loads a newly installed skill, the skill being callable right after
install proves nothing about activation — it was invoked by hand. The
installing session therefore sees everything pass (bundle complete, skill
listed, protocol ran, hook emits valid JSON) while the one thing that
matters is untested, and the tempting close is "installed and tested".
Report the install as **activation unverified** until a fresh session has
been seen invoking the skill on its own, and name the check: the next
session opens with ordinary work that names neither the skill, the log
nor the check, and only afterwards is the skill confirmed invoked (not
merely listed) with the Session Start Protocol run — by evidence of
invocation, not by a side effect that a hand invocation would also
produce. If the environment offers no way to start a fresh session from
the installing one (a GUI-only harness, no CLI), hand the check to the
user: start the next session with unrelated work, then look at the
`session-start scan` line in `checkpoints.log` or at the transcript; an
unverifiable step never closes silently as "tested". A pass from a
session whose first request named the skill is a hand invocation and is
discarded, not counted (`skill-authoring.md`, "Trial design").
The runtime cannot diagnose its own absence — Session Start step 4 only
runs once activation has already succeeded — so the external diagnostic
is the one that catches a skipped install step: **if
`skill-observations/observation-log/` does not exist after a few sessions
of tool-using work, activation never happened**; check the activation
block in the config, or install the hook. The directory existing proves
only that one session ran: a first session loaded by hand, or by a lucky
description match, writes entries and the trace, and the install then
goes quiet. So the diagnostic has a second half: **the last
`session-start scan` line in `skill-observations/checkpoints.log` is the
last session that ran the protocol** — days old while work went on means
activation is not running, whatever the log holds. The scan prints a
`GAP:` line when that date is 7 or more days old, which helps only the
session that is activated after the gap; the dated line is the check
anyone can run from outside. The README carries the same diagnostic for
users who never read this file.
**Another skill's session-start output is a false positive for
activation.** A harness that injects a different always-on skill's
content at session start makes the session look skill-governed while
this skill's activation does not exist (observed: a full working day of
real work with the skill installed beside four others, no log and no
activation block). Count only evidence of THIS skill: its own
invocation, the protocol's trace in `checkpoints.log`, or the
`observation-log/` it created. An install is not finished until an
artefact outside the skill proves it: create the workspace AND write the
activation, then print what was written and where. Where the activation
cannot be written, the install does not succeed silently: report it as
incomplete and hand over the block to paste, with its values filled in.
The same holds for a later session that finds the block unfilled and
cannot write the surface it sits in: name that surface (the file, or the
settings field) and hand over the filled-in block.
### Activation config — late, intermittent, and why the guard cannot live inside it
SKILL.md step 1 carries the instruction (on turn 1, load the session-start
skills directly rather than assuming the config did, and read the config
yourself if the mount resolves but its content is not in context). This is
the reasoning behind it, and the reason that instruction is only the backup.
In some hosted or bridged session types the activation config — a project
instruction file, a session-start hook's context — does not reach context
until the **second** user turn, while the workspace it lives in is already
mounted and probes clean. From inside turn 1 a config that is merely late is
indistinguishable from one that is absent, so a whole substantive turn can
run with no session-start skill loaded. **A config delivered on a later turn
than the work it governs is equivalent to an absent one for that work.**
It has also been seen **intermittent** rather than merely late: present for
turns 2 and 3 of a bridged session, then reported as no longer present at
turn 4, with no change in the workspace link and nothing the session did to
cause it. So a rule anchored on "once it arrives it stays" fails the same way
a rule anchored on "it arrives first" does. Do not treat an earlier turn's
config as still in force.
**The skill listing lags the same way, and an absence verdict expires the
same way.** The instruction can be present and fire on a turn where the
skill it names does not yet resolve against the harness's own listing of
invocable skills — right after the instruction was added mid-session, or
in a harness that builds its available-skill list once near session
start. The honest response on that turn is a disk check and "not
installed", and that verdict is true only for the turn it was made on;
nothing revisits it, so when the listing catches up every tool call in
between went unobserved and the earlier claim stands uncorrected. So a "not installed" verdict
names the probe it came from — the listing lookup, or a disk check of the
skill directory — because the two disagree exactly here, and it holds for
one turn: re-check the listing on each later turn that makes a tool call,
and run the Session Start Protocol in full the first time the skill
resolves. Like the guard below, this rule cannot live only in the skill
that failed to resolve; the line that carries it is in the activation
block.
**A listing can also omit an on-disk skill for good.** Some harnesses never
list a skill whose directory resolves and is complete, session after
session, so a Skill call fails every time and the re-check above never
fires. When the listing lacks the skill and its `SKILL.md` resolves on
disk, the disk load is the supported activation for that session: read
`SKILL.md` from the installed directory, run the protocol with the
scripts there, say once in the start-up lines that the skill was loaded
from disk because the listing omits it, and make no further Skill call for
it that session. Tell the user once that the listing omits an installed
skill, so they can check the harness's skill settings; the omission is a
harness fact, not a defect in the bundle.
The durable form: **a guard against an activation config failing to load
cannot live inside the thing that config loads.** The guard in SKILL.md step
1 is in `task-observer`, which is loaded *because* the config says to load
it — so on the turn where the config is missing, nothing puts that guard in
context either. By construction it cannot fire on turn 1.
The primary guard therefore belongs in the earliest channel verified present
on turn 1 — in most harnesses the user-level preferences or system-prompt
block, which is where the line
> then read the workspace config and follow it before any other work
goes. See the activation tiers above: that channel is tier 2 (user-level preferences), and the step-1
guard is the backup for turns 2+ and for sessions where the skill happens to
be loaded directly.
**Log the cause, not just the miss.** When a session-start load is skipped,
the fix depends on which of these it was: *absent* (config unreachable),
*present-but-not-yet-injected* (late — record the turn it arrived),
*present-but-not-yet-resolving* (the instruction fired and the skill was
not in the listing — record the turn it appeared), *present on disk and
never listed* (the disk load above), *present and skipped*
(attention), or *loaded-but-not-run* (the invocation succeeded and the
protocol inside it never executed). Only the first two are fixed by
changing the channel, the third by re-checking the listing, and the
fourth by the disk load and the harness's skill settings; the last two are
not environmental, and an environmental cause found first will
otherwise absorb the whole explanation.
### The probe rides inside the first batched call
The probe line can be present and correct on turn 1 and still not fire
first: the session's first tool call is a batch of `Skill` invocations,
and the probe rides in the second. The failure is detectable only in the
sessions where it costs nothing, and it costs everything in the session
where the folder is not there and the agent asserts that it is.
The cause is a contest for one slot: loading the session-start skills is
the one action that genuinely *is* prior to the work, so it recruits the
"before anything else" position the probe needs, and feels like
preparation rather than action. Stating the precedence more firmly does
not change that, because the load discharges the felt obligation.
So the rule is about the **content of the first call, not its order**: the
session's first tool call is a single batched call that contains the probe
— a listing of the pinned workspace path through the tool that reaches
that filesystem, a device call in a bridged session; if that tool's server
is still connecting, a tool search for it in batch 1 and the listing as
the first call of batch 2 — the target is the test, not the command's
success — and any session-start skill loads ride in that same batch,
never in an earlier one. That removes the contest instead of adjudicating it, the
harness's parallel-call guidance already permits it, and it is checkable
after the fact from the transcript (an ordering rule between two "first"
actions is not). SKILL.md step 1 states it that way; the tier-2 preferences
line above is worded to match; the activation block names the same batch
(the listing, the skill load and its per-skill lookup), so its "before the
first tool call" is satisfied by the load riding *in* that call.
**The pre-skill tier's line names the complete batch, not only the
probe.** Whatever the harness reads before any skill — Cowork's
user-preferences block, a Claude Code user-level (global) CLAUDE.md, a
session-start hook's injected text — carries the whole first batch: the
workspace probe AND the session-start skill loads, named, in one batched
call; the tier-2 line above is the template. The failure shape: a line naming only the probe
fires the probe and leaves the loads to a project config that arrives late
or intermittently, so the first batch carries the probe alone and the
skills load a batch later. The review's activation regression pass checks
for it (`weekly-review.md`, Step 1).
**A deferred probe tool moves the probe to batch 2.** In a cloud session
bridged to the user's computer, the device tools may still be connecting
at turn start and arrive deferred (name only, schema not loaded), so the
probe cannot ride in batch 1. Batch 1 then carries the deferred-tool load
together with the session-start skill loads; batch 2 carries the probe,
the session-start scan and one `skill-load.sh` call per skill loaded in
batch 1 — the one recorded exception to the lookup riding in its load's
batch, because the script runs through the same deferred tool (scripts
absent from the device: "Environment mappings", "Where the scripts are not
on the device"). Where the device shell is the only channel to the log,
the per-skill lookup and its checkpoint line therefore ride in the batch
that carries the probe, and that is not a batch-split finding: the rule
that the lookup rides in its load's batch assumes a channel the load's
batch has. Record the split in the start-up lines ("probe in batch 2: device
tool deferred"), so a review reading the transcript sees an environmental
order, not a skipped rule. The failure shape: a rule that names batch 1's
content cannot be met when one of its tools does not exist yet, and an
unrecorded workaround reads the same as a violation.
**A server still connecting is the same split with nothing to load.** When
the server providing the probe is still connecting, its tools are absent
from the tool surface, deferred list included, so batch 1 has no probe call
to carry. Batch 1 then carries the session-start skill loads plus the tool
search that waits for that server; the probe is the first call of batch 2,
and the start-up lines say so ("probe in batch 2: device server still
connecting"). Never put a placeholder command in the probe's slot — an
`echo`, or an `ls` of the cloud container: it probes nothing and reads in
the transcript like a probe that passed. In a session with two filesystems
a container `ls` never counts as the workspace probe. The one-line test,
applied without judgement: **a probe of a bridged path issued through the
cloud shell is never a probe — the channel has to be the one that reaches
that filesystem.** A command addressed at the right path through the wrong
channel cannot fail informatively, and its failure reads like an unmounted
folder; name the channel, not the intent.
**A failed probe has three readings, and the parent tells them apart.**
The pinned path is absent on the first run of every install, because
nothing creates `skill-observations/` before the first session does; a
probe read as "not mounted" sends that run to the folder picker, which
grants the path it already had, or in a harness without a picker to
handoff-doc mode, where the log is never created at all. So a failed probe
is split before any branch is chosen, by one `ls` of the pinned path's
parent: it resolves and is writable → a first run: run "Workspace
creation" (`observation-log.md`) and continue; it resolves read-only → the
grant precondition above ("A grant names a path; it does not create
one"); it does not resolve → a missing mount, and the folder picker is
the first response. The per-skill lookups that rode in the probe's batch
ran against no log: after a first-run creation, re-run the lookup once
per skill loaded in that batch, so `checkpoints.log` holds the
`workspace: created=…` line followed by one `loaded` line per skill.
**A missing mount in a bridged session is asked for in the same turn, and
re-probed while it stays missing.** When the probe fails because the
workspace folder is not connected, the folder-access request goes out in
the batch right after the failed probe, before any work, with the tool's
schema loaded in that batch if it is deferred; the deliverable never goes
first with the request after it. While the probe keeps failing (the folder
not granted, the computer unreachable), re-probe through the same channel
at each task boundary, where the per-task backstop runs; say so once in the
reply and again only when the state changes, and run the Session Start
Protocol in full at the first probe that succeeds.
**An unfilled pin is an unfinished install, not a failed probe.** Read the
pinned value before probing it. A value that still reads as a template
placeholder (`[ABSOLUTE PATH]`, `[PROJECTS ROOT]`, `<skill directory>`) or
is not absolute (`/…`, or a drive letter on Windows) was never filled in:
none of the three readings above applies, because the parent of a
placeholder is the working directory, and a first-run creation there makes
a folder named after the placeholder. Report "unfinished install: the
workspace path in <the file or settings field holding the block> was never
filled in", run the anchor search ("Before creating a log, search for
one"; in a bridged session through the device tool), and ask the user once
for the path, offering any workspace the search found. Never probe the
literal, run Workspace creation on it, or open the folder picker for it.
Where this session cannot write that surface (an account-level preferences
field, a file outside its reach), hand over the filled-in block to paste
and name the surface ("Verify activation in a NEW session", the install
report).
### A failed session-start probe
Session Start step 1 points here when its probe of the pinned path fails.
A failed probe is split before any branch is chosen, by one `ls` of the
pinned path's parent: the parent resolves and is writable → a first run,
not a missing mount — run "Workspace creation" (SKILL.md step 1), then re-run the
per-skill lookup once for each skill loaded in that batch; it resolves
read-only → a grant that names a path it cannot create
(`references/environments.md`, "Anchoring the workspace"); it does not
resolve → the folder-picker tool (in Cowork, `request_cowork_directory`;
elsewhere, its equivalent), never the "no filesystem" branch (handoff-doc
mode), which a missing mount read as no filesystem reaches too easily. A
permission-classifier refusal of that request (it names the classifier and
gives a bracketed reason; a user decline does not) falls under the **How
to Log** denial rule: at most one identical retry, told to the user, never
another tool. Refused again, or no folder-picker or device-bridge tool
after one tool search: load `references/environments.md` ("No link to the
user's computer"), mandatory, and keep its order — the log, else ask to
park in the user's memory inbox, else a handoff file.
### Install-layout hazards — three ways a skill silently stops existing
Each of these leaves no error. The skill simply stops being offered, or an
activation tier stops firing, and the only symptom is that the Session Start
Protocol no longer runs — which is indistinguishable from a session where it
ran and found nothing.
**Skill discovery is exactly one level deep.** The host reads the skills
directory and looks for `<entry>/SKILL.md`. There is no recursive lookup. On
a library of any size the natural organising instinct is to group skills into
category folders — `skills/seo/`, `skills/clients/`, `skills/writing/` — and
doing so makes **every skill inside them cease to exist**: no error, no
notice, no change in behaviour except that the skills stop being offered.
The layout is not merely the happy path; it is the rule, and it does not
travel with the maintainer who reorganises six months later. Keep every
skill directly under the skills directory.
**A backup inside the skills directory registers as a rival skill.** The
obvious way to back a skill up before overwriting it —
`cp -r ~/.claude/skills/task-observer ~/.claude/skills/.task-observer-backup`
— puts a second copy where the host is looking. The leading dot does not
exclude it from discovery. The available-skills list then holds two entries
with near-identical descriptions, and the backup still advertises the OLD
version's trigger, including its session-start instruction. That defeats the
upgrade at the one activation tier that survives an unreachable config:
description matching now has two candidates competing for the same trigger,
one of them the file the upgrade just replaced. Back up **outside** the
skills directory. The same holds for any second copy the host loads — a
user-owned copy beside an account-synced one: the older copy is a second
writer in the old format (the scan's SPLIT STORE line is how it shows),
so name each copy's version when more than one resolves.
**A hook registered by script path dies when the exec bit goes.** The
docs' example reads most naturally as naming the script directly:
```json
{ "type": "command", "command": "'/path/to/hooks/task-observer-activation.sh'" }
```
Anything that rewrites file modes — a cloud-drive resync switching between
stream and mirror mode, a restore from an archive, a checkout on a
filesystem without permission bits — returns the file as mode 600, and the
hook then fails with "permission denied" on every session start with
nothing surfacing the error. Register the interpreter instead
(`"command": "bash '/path/to/hooks/…'"`), which does not depend on the exec
bit, and treat "the Session Start Protocol stopped running" as a prompt to
check the hook rather than the skill. The same silent death follows, with
the mode intact, when the script lives on a drive that is not mounted at
session start: keep hook scripts on local storage ("Anchoring the
workspace", "Stable is not the same as always available").
### Other agent tools that read the same skills folder
A second agent tool that lists the same skills directory shows the
description to its own model, and the description starts the skill by
itself — it carries the session-start trigger so that activation
survives an unreachable config file (tier 1 above). Removing the
activation block from that tool's instruction file does not keep the
skill off there. To keep it off, use that tool's own skill-permission or
skill-path setting, or stop sharing the folder. Where it does run, the
protocol's assumptions (the pin, the permission model, the hooks) do not
hold, and a log it writes is a shard ("Before creating a log, search for
one").
### Two harness behaviours that block the protocol rather than break it
**A command-shape guard can refuse a read-only call.** Some setups run a
pre-tool hook that inspects the literal command text for governed path
segments combined with a write indicator (`=`, `>`, `cp`, `mv`) and denies
the whole call when both appear anywhere in the string — regardless of
whether the path is actually being written to. Two consequences worth
knowing before diagnosing: a `cd` into a governed directory followed by a
read-only script call is denied even though nothing is written; and a
**blocked command merely quoted inside an observation body** can trip the
same guard when that body is written through a shell. Neither is a
permission problem with the destination. Where this bites, invoke the
script with an absolute path and no `cd`, and write observation bodies with
the editing tool rather than through a shell. A guard that refuses the
session-start scan itself is handled the same way — degrade to flat
commands, never skip the step (`observation-scan.md`, "A refused snippet is
a degraded path, never a skipped step").
**Staging a harness configuration change is not like staging a skill.** A
skill's `SKILL.md` is read by itself; a corrupted staged copy fails to parse
and nothing else is affected. A harness config file — `settings.json` with
its hook entries, deny-lists and protection rules — is read by the harness,
and it commonly carries **other protections alongside** the thing being
changed. The natural delivery shape for a config change is a fragment:
"here's the new key, add it under `hooks`". A hand-merge that goes wrong
there does not fail loudly; it produces a valid file with the other
protections missing.
So: deliver a config change as a **complete replacement file** built from
the user's current one, never as a fragment to splice in; state in one line
what else that file was carrying, so the user can verify it survived; and
where the harness allows, prefer a separate file over editing a shared one.
### If CLAUDE.md (or the equivalent config) is governance-protected
Some setups guard shared config files with hooks or file-protection rules
that deny agent edits. If an edit to the config is denied, never retry the
same edit blindly and never attempt to bypass the guard — a denial is the
governance system working as intended, and a silent skip is just as bad
(the user believes activation is set up when only description-level
matching is active). Surface the denial to the user and offer these
fallbacks, lightest first: (a) if the denial came from an interactive
permission system rather than a hard guard — the denial message offers an
approval path, names a permission rule, or otherwise indicates consent
would clear it — ask the user to approve a retry of the same edit; one
confirmation resolves it, and escalating past this step spends user effort
on something already recoverable; (b) ask the user to paste the activation
block into the file themselves; (c) if the user's environment provides its
own temporary-authorization mechanism (a marker file, an environment
variable, or similar), ask the user to authorize the edit through that
mechanism and revoke it afterwards; (d) where the platform supports
unguarded project-level instruction files, add the activation instruction
there instead. Branch on whether the denial is retryable-with-consent or
categorical: an interactive permission prompt is cleared by asking, a hook
or file-protection rule is not, and collapsing both into "hand the task
back to the user" is safe but consistently over-escalates. Never assume
unrestricted edit access to shared or governance-tracked config — many
setups gate exactly those files.
**The same shape applies to a blocked hook installation.** The hook
option from the same paragraph writes to the harness's settings file or
hooks directory, and those are gated at least as often as the config
file. A denied hook install follows the rules above unchanged: never
retry the same install through a different tool or path, never bypass,
surface the refusal, then fall back lightest first — ask for a retry if
the denial is retryable-with-consent; ask the user to add the hook entry
themselves (hand them the exact JSON or script); use a temporary
authorization mechanism if one exists; and if the hook cannot be
installed at all, fall back to the declarative config instruction, saying
plainly that the enforced tier is not in place and the probabilistic one
is. A hook that silently failed to install is worse than none: the user
believes the strongest tier is active.
### A third denial class: an automated content classifier
The fallbacks above branch on two kinds of denial: a hard guard (a
governance hook, a file-protection rule) and an interactive permission
prompt that one user approval clears. A third behaves like neither.
An automated content classifier can refuse the edit on the grounds that the
activation block is **third-party instruction text being written into a
user-scope config**, where it will steer every future session. Reported in
the field as `Instruction Poisoning`, on a fresh install into a global
Claude Code skills directory.
What follows from that:
- **The refusal is a valid outcome, and the user sees it first.** Stop.
Quote the refusal and what it objected to, and explain the trade-off it
points at: the block is always-on third-party instruction text in a
global config, steering every future session, which is a real cost the
user is entitled to weigh. Only then offer options.
- **Rewording does not help.** The objection is to provenance and always-on
scope, not to the phrasing, so there is no lighter version to retry.
Shortening the block and trying again is the obvious move; it fails, and
it is a rewrite aimed at the classifier rather than at the user — don't
make it.
- **The options, in this order.** (1) The user pastes the block into the
config themselves (fallback (b) above): the decision then sits with the
person whose config it is. (2) A permission-mode change, presented as
the user's decision with its implications stated: it changes what the
harness lets the agent do without asking for the rest of the session,
and it takes the classifier out of this write without answering its
objection. (3) Leave activation at the
description layer and say plainly which tier is in place.
- **The objection follows the content, not the file.** A documentation
page that quotes the activation text can be refused on the same grounds
as the config edit. Report the setup as incomplete while either the
config or its write-up has not landed, and do not reword either to get
past the classifier.
**The ladder is not monotonic.** Tier 4 — the session-start hook, which this
file elsewhere calls the only enforced option — can be blocked *harder* than
tier 3, and for an unrelated reason. In the same install the hook was
refused as `Auto-Mode Bypass`: configuring a hook changes what the harness
executes automatically, which that permission mode withholds categorically
rather than on content. Writing the hook *script file* alone, wired to
nothing, was refused on the same grounds. So tiers 3 and 4 failed for
different reasons that happened to coincide, and the tier presented as the
robust fallback for a blocked config edit was the one held furthest out of
reach. Do not present the ladder to the user as "if 3 fails, 4 will work".
### A mode that forbids every write by design
Some modes — Claude Code's plan mode, any propose-only mode — permit
every read and refuse every write for the whole turn. That is not a
denied write: a retry is a wasted call, the log is not unwritable, and a
denial report is the wrong report when the environment is telling the
truth. A gatekeeper and a mode are different failures — a gatekeeper's
denial is reported to the user and its observations carried in
report-back or handoff mode (SKILL.md, How to Log); a mode is accepted
and its writes deferred.
1. Run the read steps normally: the scan, the review-date check, the
per-skill lookup. A read-only session is fully observant. Run them
in a command of their own, without the scan's `checkpoints.log`
append: a mode can refuse a command that mixes a read with a write as
a whole, and the refusal takes the reads with it. The scan script
writes that line, so a mode that refuses it gets the flat reads
(`observation-scan.md`, "A refused snippet is a degraded path, never a
skipped step").
2. Defer, never skip, the writes: storage creation, `.id-floor`,
archival, the `checkpoints.log` line. Ids are resolved at flush
time, never now.
3. Queue pending observations where the turn cannot eat them: a
numbered list in the plan or handover text itself. A rejected plan
still leaves its text in the transcript; working memory does not
survive the turn.
4. Flush in the first write-capable turn, before other work, running
the id snippet (or the helper) before each write. End the deferred
`checkpoints.log` line with `(deferred from <mode>)`, so a reader of
the file dates the protocol to the session start, not to the flush.
Tell the two apart by the refusal's own words: a mode names itself and
refuses every write, a gatekeeper names a classifier or a rule and
refuses one call. Observed in one harness: plan mode refused an append
to an existing `checkpoints.log` as well as a create. Defer both either
way, so the flush turn is the only one that writes.
### A delegated setup step is not done until you have observed it
Every fallback above ends by handing something to the user: paste this
block, add this hook entry, authorize this edit. The instruction is where
the hand-off ends today, and that is one step short.
**So pair every handoff with a check you run yourself**, in the same
session, and report the result:
- `grep` the config file for the skill name;
- compare the file's mtime against the moment you handed the block over;
- for a hook, confirm the harness lists it, not merely that the file exists.
"The user says they pasted it" is a claim about the world. An install can
check it, cheaply, and should before declaring itself configured: a
delegated setup step is complete when the agent has independently observed
the resulting state, and an unverified handoff and a silently skipped step
produce the same artefact — a setup both parties believe is done.
### Paths handed across a boundary are resolved from the far side
A path the agent has verified from inside its own execution context proves
nothing about the same string in the user's hands. Three boundaries, each
observed in one install. **Packaging:** inside a Store-packaged (MSIX)
desktop app on Windows, `%APPDATA%\<App>` is transparently redirected to
`%LOCALAPPDATA%\Packages\<App>_<id>\LocalCache\Roaming\<App>`, so every
check the agent runs — bash, PowerShell, Python — finds the config file
there, and a script the user starts from Explorer, outside the package,
finds nothing; processes started from the app's own terminal die with the
app, so "run it after quitting the app" cannot be done from inside either.
**Sync redirection:** `%USERPROFILE%\Documents` is not the Documents
folder Explorer opens once a cloud drive has redirected the known folder;
resolve user folders with the shell's known-folder lookup
(`[Environment]::GetFolderPath('MyDocuments')`), never by composing them
from the profile path. **Shell dialect:** a Git Bash drive path
(`/c/dev/<repo>`) passes every pre-flight in Git Bash and fails in the
PowerShell the user opens (`fatal: cannot change to '/c/dev/<repo>'`);
`"C:/dev/<repo>"` works in PowerShell, cmd and Git Bash alike. The same
shape at the plugin boundary: `python plugins/<p>/scripts/x.py` and "show
`docs/<file>.md` from this repo" are correct in the author's checkout and
absent for every consumer, because installation copies only the plugin's
own directory. So: on a packaged host keep the workspace and any hook
script outside `AppData`; resolve every path handed to the user — hook
script, config, workspace — once from the user's side of the boundary
before handing it over; and make that resolution a step bound to the
hand-off, not a principle consulted while authoring.
**An install is a path handed across the same boundary.** A tool installed
for the user from the agent's shell inside a packaged app — a global npm
install, a per-user pip install, anything that writes under a redirected
`AppData` path — lands in the package's `LocalCache`, and every check the
agent runs from inside finds it where it was expected. Install from the
user's side (a command the person runs in their own terminal), or say in
the hand-off that the install is visible only inside the app. Not every
`AppData` path is redirected (`%TEMP%`, under `AppData\Local`, was not on
the host where this was observed), so "under AppData" is a first
approximation; a check from the far side settles a given path. **Process
state does not cross either.** The agent's shell can carry a process-level
execution policy and its own `PATH`, so a pre-flight run inside proves
nothing about the user's default policy (`Restricted` on a Windows client
unless changed) or about which commands their terminal finds: hand npm
tools over — `npm` and `npx` included — in their `.cmd` form, which the
policy does not govern, not as the `.ps1` shim it refuses. The app's own
terminal panel is a child of the packaged app and inherits its startup
environment, so it is not the user's side either.
**An assistant's own sandbox is the same boundary.** A home-relative path
inside a cloud container or a sandboxed agent is not on the user's
computer, and an install reported there reads as complete. So an install
report names every path absolutely, with the host it is on (the user's
computer, a cloud container), and confirms it through a route that does
not pass through the sandbox that made it: a device tool, or a listing the
user runs.
**Resolving from the far side on a packaged Windows host — only with the
user's explicit go-ahead.** `explorer.exe` starts what it opens outside the
package, so a script started through it runs on the user's side of the
sandbox. That is a deliberate step outside the agent's own execution
context: tell the user what the script does and that it runs outside the
app, and run it only once they have said yes in that session — never as a
silent fallback. The recipe: write a pure-ASCII `.cmd` under
`%USERPROFILE%` (not under `AppData` or `%TEMP%`), start it through
Explorer, wait for a completion file, and read the output. A **vantage
marker** written under `%APPDATA%` from inside exists only inside the
package, so the result counts only if its first line is exactly
`vantage-marker-visible: False`; `True` means the vantage is unproven,
never a pass. The **completion file** keeps the read from racing the
script. The script travels as `-EncodedCommand`, which the execution
policy does not govern (it governs script files) — say so when asking,
since the user may have set that policy on purpose; the `.cmd` expands
`%USERPROFILE%` at run time, so it stays ASCII on a non-ASCII profile
path; `$ProgressPreference = 'SilentlyContinue'` keeps a CLIXML progress
block out of the output. Replace the last two probe lines with whatever
the hand-off needs resolved.
```powershell
$id = [guid]::NewGuid().ToString('N').Substring(0,8)
$dir = Join-Path $env:USERPROFILE 'farside'
New-Item -ItemType Directory -Force $dir | Out-Null
$marker = Join-Path $env:APPDATA "farside-marker-$id"
Set-Content -LiteralPath $marker -Value x
$markerLit = $marker -replace "'", "''" # a profile path may hold an apostrophe
$out = Join-Path $dir "out-$id.txt"
$script = @"
`$ProgressPreference = 'SilentlyContinue'
"vantage-marker-visible: " + (Test-Path -LiteralPath '$markerLit')
"policy: " + (Get-ExecutionPolicy)
"npm: " + ((Get-Command npm.cmd -ErrorAction SilentlyContinue).Source)
"@
$enc = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($script))
$cmd = Join-Path $dir "run-$id.cmd"
Set-Content -Path $cmd -Encoding Ascii -Value "@echo off`r`npowershell.exe -NoProfile -NonInteractive -EncodedCommand $enc > `"%USERPROFILE%\farside\out-$id.txt`" 2>&1`r`necho done> `"%USERPROFILE%\farside\out-$id.txt.done`""
Start-Process explorer.exe $cmd
$deadline = (Get-Date).AddSeconds(60)
while (-not (Test-Path "$out.done") -and (Get-Date) -lt $deadline) { Start-Sleep -Milliseconds 500 }
if (Test-Path "$out.done") { Get-Content $out; Remove-Item $cmd, $out, "$out.done" } else { 'UNVERIFIED: far-side run did not finish in 60 s (files left in %USERPROFILE%\farside)' }
Remove-Item -LiteralPath $marker
```
### Windows hosts: what reaches the shell and the file
Two Windows transforms change content and report nothing.
**Backslashes through an agent's Bash tool.** Where the agent's Bash tool
runs Git for Windows' bash and hands it the whole command as one `-c`
argument, runs of backslashes have been observed to arrive halved
anywhere in the command — inside single quotes and quoted heredocs too —
except directly before a double quote; a single backslash arrives intact,
and the same command run from a file arrives exact. A body written through
that shell loses one backslash of every `\\`, and an inline snippet that
carries `\\` runs altered: the session-start scan's `suspect` program,
halved, is rejected by gawk, mawk and BWK awk, so the count reads 0 with
an error on stderr — why the scan ships as `scripts/session-start-scan.sh`,
whose one-line invocation carries no backslash. Test a host once with
`printf '%s\n' 'a\\b' | od -c`: two backslashes in the output mean the
transport is exact. Where it is not, write observation bodies and any
other content holding backslashes with the editing tool, and run a
snippet that carries `\\` from a file written with the editing tool
(`bash <file>`). Very long inline commands have also been reported cut on
the same transport, so keep inline commands short and put long content in
files. A hook or proxy that rewrites commands on any host is the same
fault: `observation-scan.md`, "Every instrument gets the same guard".
**A byte order mark from Windows PowerShell.** PowerShell 5.1 writes UTF-8
with a BOM (`Set-Content -Encoding UTF8`, `Out-File -Encoding utf8`).
Every header reader tests line 1 for `---`, so an entry written that way
drops out of the session-start scan — `parsed` one below `files`, with no
notice while other headers parse — and the archival sweep never moves
it. Write entries with the editing tool or the helper script; in
PowerShell 7, `-Encoding utf8NoBOM`.
## Environment mappings
The procedures in this skill are written as capabilities. This table is
the only place product-specific names live; when a step says "present the
staged file" or "register the review", look up the current environment
here rather than guessing a tool name.
**Cowork execution mode — cloud vs local is a user setting.** Cowork can
run a session in two modes with materially different tool surfaces, and
the platform's default moved to cloud, so an upgraded install may silently
change mode. The switch: Settings → Cowork → "Run new tasks in the cloud"
(plus a "Beta" button at session start). The tell: the local-filesystem
permission tool (`allow_cowork_file_delete`) present in the tool surface
⇒ local session; absent ⇒ cloud. What differs:
| Capability | Local session | Cloud session |
|---|---|---|
| Scheduled-task editing | desktop scheduled-task tools | draft instructions only; the user applies them on the Scheduled tasks page |
| Deleting workspace files | permission gate (`allow_cowork_file_delete`) | no delete tool; rename-away only |
| Git on the mounted workspace | with the delete grant | never — use a sandbox clone |
| Locally-installed MCP servers | reachable | unreachable unless proxied via the desktop app |
| Working-file persistence | workspace folder persists | files not handed back are not kept |
| Runs while the computer is off | no | yes |
Steps that must edit scheduled tasks, delete workspace files (review
cleanup, keep-two pruning), or run git in the shared folder need a local
session — treat that as a one-line precondition on those steps, and when
reporting a mode-conditional limit, name the mode and the switch with it.
**A cloud session bridged to the user's machine writes observations
through the device shell, at write time.** In a bridged session the agent
runs in a container while the log lives on the device, reached through a
remote shell (`device_bash`) and a file-commit tool
(`device_commit_files`). An observation is created on the device by that
shell running the id snippet (SKILL.md, How to Log) — or
`scripts/new-observation.sh`, where the script is reachable on the device
— at the moment of writing, and its body goes into the created path
through the same shell with a quoted heredoc: into a scratch file first,
with `__ID__` and `__DATE__` as placeholders, handed to the helper's
`--body` so the id reaches the body without an unquoted expansion
(`observation-log.md`, "Editing an existing observation"). It is never
composed in the container and committed afterwards. The failure shape: a committed file
carries an id derived from a listing taken earlier, and the prefix guard
never ran because it lives in the command the commit bypassed; the lagging
`.id-floor` appears first and the duplicate id at the next review.
**Where the scripts are not on the device.** In a bridged session the
installed skill tree, scripts included, can exist only in the cloud
container while the log lives on the device. First look for the review's
copy at `skill-observations/.bin/`: its `MANIFEST` carries
`verified_against: <version>` and a sha256 per script, refreshed by every
review that confirms an install (`weekly-review.md`, Step 1 gate). The digest that decides is
the INSTALLED script's, hashed in the container — never `.bin/`'s own:
the manifest was written from that copy, so hashing `.bin/` against it is
a tautology that passes a stale cache under a newer install. The check is
one command, so the wrong operand cannot be chosen: hash the installed
scripts in the container, headed by the installed `SKILL.md`'s version
line (`metadata.version`, or a top-level `version:` on an older install, written unindented), pass that output to the device as a file (the command per
environment is a row of the table below: "Refresh the digests"), and run
every `.bin/` script through
`bash "<root>/skill-observations/.bin/bin-check.sh" "<root>" <digests-file> <script> [args]`,
which compares each `.bin/` file with the installed digests and refuses to
run on any difference (exit 3). It also refuses when that installed version
is newer than the MANIFEST's `verified_against:`, or the MANIFEST lacks the
line, so the install that outdates the copy fails closed; a digests file
without that version line takes `--installed-version <v>` before `"<root>"`,
and with neither the version gate is skipped with a note. The check runs at session start, before the
first `.bin/` script — the scan included — never at the next review: on a
refusal, or where `.bin/` holds no `bin-check.sh` (compare the installed
digests with `.bin/MANIFEST` instead), refresh `.bin/` and its MANIFEST from
the installed scripts in the same batch (`weekly-review.md`, Step 1 gate,
names the refresh), then run the scan. Where `.bin/` is absent or cannot be
refreshed, look for another copy in the workspace — a
staged copy under `skill-updates/*/task-observer/scripts/` — and compare its
digest (`md5sum` or `sha256sum`, run on both sides) with the installed
scripts BEFORE running it, and run it only on a match: a staged copy can
be an unreleased version that nothing refreshes on install. With no
matching copy, transfer the scripts to the device — a
permission-classifier denial of that transfer gets at most one identical
retry, told to the user (SKILL.md, How to Log) — or run the inline id
snippet through the device shell. Never a hand-derived id. SKILL.md step
6's compare follows the same split: `diff-staged.sh` needs both trees in one
shell (from `.bin/` through `bin-check.sh` where the scripts are not on the
device); with staged copies on the device and live in the container, run
`(cd <dir> && find . -type f -exec sha256sum {} + | LC_ALL=C sort)` in each
shell and diff the two listings — a differing `SKILL.md` then gets the
frontmatter compare (`weekly-review.md`, "Staged-work reconciliation gate").
**Through the device shell, the scan always writes its entries to a file.**
The shell's result is capped and the scan's output grows with the log, so
"read it whole" and the cap collide, and a cut follows. Remove the
collision in the invocation:
`e=$(mktemp) && bash "<root>/skill-observations/.bin/bin-check.sh" "<root>" <digests-file> session-start-scan.sh --entries-to "$e" "<root>"`
(the same option on a direct run of the scan), then read `"$e"` when a step
needs the entries. Stdout then carries the findings, the counts and the end line.
| Capability | Claude Cowork | Claude Code | Web chat / no filesystem |
|---|---|---|---|
| Persistent workspace | the shared folder | pinned absolute path (see activation block) | none — handoff-doc mode below |
| Live skill files | `.claude/skills/{skill}/` on a read-only mount (writes fail with EROFS) | `~/.claude/skills/{skill}/`, ordinary writable files — no guard | n/a |
| Present a staged file for install | the file-presentation tool (`present_files`) with its upload button; where the harness's own instructions name its skill card as the install route instead, the card (`acting-on-observations.md`, "The skill-save control") | none — report the staged path and a change summary in chat | paste into the handoff doc |
| Scheduled review | the app's scheduled tasks (cloud-default: run remotely; legacy local mode: run on the user's machine, only while it is on — see the execution-mode note above) | cron / an account-level scheduler that can reach the workspace — headless invocations carry the workspace grant (`--add-dir`) in the task definition; a `SessionStart` hook reports the review state, it does not run the review | calendar reminder + manual trigger |
| Session-start hook | none | `SessionStart` hook (`hookSpecificOutput.additionalContext`) | none |
| Local-vs-cloud tell | `allow_cowork_file_delete` present ⇒ local session | n/a | n/a |
| Refresh the digests `bin-check.sh` reads ("Where the scripts are not on the device") | cloud session bridged to the device: `{ grep -m1 -E '^[[:space:]]*version:' "<skill directory>"/SKILL.md | sed 's/^[[:space:]]*//'; sha256sum "<skill directory>"/scripts/*; } > digests.txt` in the container, then the device file-commit tool carries that file to `[ABSOLUTE PATH]/skill-observations/.bin/digests.txt`; local session: the scripts are on the device, so `sha256sum` writes the file there directly | `{ grep -m1 -E '^[[:space:]]*version:' "<skill directory>"/SKILL.md | sed 's/^[[:space:]]*//'; sha256sum "<skill directory>"/scripts/*; } > "[ABSOLUTE PATH]/skill-observations/.bin/digests.txt"` — one shell, nothing to carry | n/a |
**The Claude Code column is the terminal CLI; the desktop app has a
scheduler of its own.** Claude Code run inside the desktop app exposes
the app's scheduled-task tools on its tool surface, and a review
registered there is local: it runs on the user's machine while the app
is open and catches up at the next launch (reported, not yet confirmed
here). Register it as any local scheduler: the workspace grant goes into
the task definition, and the first "Run now" of the task itself is the
grant check (the access-grant paragraph below). The tell is a
scheduled-task tool on the tool surface; absent, the CLI column applies.
Where scheduled sessions already run for other jobs, register a dedicated
`weekly-skill-review` task all the same: none of them reviews unprompted
("Sessions whose output channel is owned by a caller").
Grow the table when a new environment appears; do not scatter its tool
names through the procedure files.
**A scheduled-task prompt's first listed action is its first tool call.**
The Session Start Protocol wants the workspace probe (step 1) before any
skill invocation, and a scheduled prompt that opens with "invoke, in this
order: …" makes the first invocation the first call. A rule that wants something before the
first listed action has to appear in that list, not in the text the list
loads: write the activation pointer in every scheduled prompt as "probe the
workspace folder (one `ls` of its absolute path, through the tool that
reaches it; in a bridged session whose device server is still connecting,
a tool search for the device file tools, then the listing as the first
call of batch 2 — never a shell command in its place), then invoke
<skills>", and keep the probe's procedure and failure handling in the
skill. The clause names the channel so a run that reads only the prompt
cannot substitute a shell command for the probe.
**The second listed action leaves a started marker.** After the probe,
every scheduled review prompt writes the date and time to
`skill-observations/review-started.txt`, and the review's Step 8
overwrites it with `completed <date>`:
```bash
printf '%s\n' "$(date '+%F %H:%M')" > "[ABSOLUTE PATH]/skill-observations/review-started.txt"
```
The review's Step 5 overwrites it with `started <date> <time> <label>
step5 <anchor>` as it claims its anchor (`weekly-review.md`, Step 5), so an
interactive or commissioned review leaves a live claim too. A scheduler's
"succeeded" says the job launched; the marker says how far it got. At the next session start, a marker that does not read
`completed` is a run that died mid-way, and a scheduler last run later
than `last-review-date.txt` with the marker untouched is a run that fired
and never reached its second action — two different defects, and neither
is a review that happened. The marker is judged by its content, never by
its mtime: Step 8 writes it after the date file, so a completed run's
marker is always the newer of the two.
**The access grant is part of the task definition, not of the path.** A
scheduled session runs in the sandbox the scheduler creates, and that
sandbox can deny a path that exists and is online — through every
interface, a junction inside the allowed area included, because the
sandbox canonicalises the target — and the run ends with the offline
policy's one-line skip: a config gap wearing the costume of a transient
outage. Registering a scheduled
review therefore includes whatever allowed-directory configuration the
harness needs for the workspace root — for Claude Code headless,
`--add-dir "[ABSOLUTE PATH]"` on the invocation, or the equivalent
permissions rule — and the setup is not done until one firing has
reached the workspace **and left one write there** (the review record or
`last-review-date.txt`) **from inside the task's own execution context**:
an interactive test proves nothing about the sandbox the scheduler
creates, a task the scheduler lists is not a run that succeeded, and a
firing whose report says a write was refused is a failed setup, not a
review that ran. Claude Code headless (`claude -p`) can refuse writes
under `~/.claude/` through the Edit and Write tools as a sensitive file,
with nobody present to approve, while Bash writes pass; a Write under a
project's own `.claude/` folder is refused too, and an `Edit(path)` allow
rule did not lift it, while `Write(...)` rules are not matched at all
(reported on one install, tested): for a scheduled
review, anchor the workspace outside any `.claude/` folder or prove the
write on the first firing. (The run-time skip note:
`references/weekly-review.md`, offline-workspace policy.)
**Managed skills directories (dotfile managers, sync tools).** Where the
skills directory is generated by chezmoi, GNU Stow, yadm, a symlinked
dotfiles repo or any sync tool, the live path is not the source of truth:
copying a staged update onto it succeeds, looks installed, and is
silently reverted at the next `apply` — "I installed it" and "it is still
in effect" become indistinguishable. Detect the manager at install (a
symlink into a dotfiles checkout, a `.chezmoi*` marker, the directory
listed in a Stow package) and record it in the activation config. Then
install into the manager's SOURCE, not the live path, and let the manager
apply it; or exclude the skills directory from management. "Always start
from the live file" (`references/skill-authoring.md`) still holds for
READING — the live file is what the loader loads — but the WRITE-BACK
path is the manager's source. The weekly review's staged-work
reconciliation (`diff -rq` staged vs live) is the check that catches a
reverted install: run it at the session after any install on a managed
directory. Where the entry is a symlink, resolve it before staging as
well (`skill-authoring.md`, editing rule 1): a link copied as a link
makes the staged path the live one.
## Git as an optional staging medium
Staging a skill update as a branch or commit the user merges gives the
same guarantee as the `skill-updates/` directory — nothing goes live
without a user action — plus diffs, history and rollback, and it suits a
multi-device setup that syncs skills through a private repository. It is
an option, not a change to the default: the review still writes the
staging manifest, still never edits the live install, and still presents
the change for a decision. Treat the version-control commands as a
mutation surface for the observation log (`references/observation-log.md`).
## Claude Code Projects
*Based on the platform's documentation, not yet field-tested — reports
welcome.* Re-verify each claim below against the current Claude Code
documentation before relying on it.
Claude Code Projects run work as parallel cloud "threads" under one
coordinating conversation. Per the documentation, a thread picks up
nothing from the Claude Code setup on the user's own machine: skills load
only from `.claude/skills/` in a repository added to the project, or from
skills enabled on the account; CLAUDE.md loads only from the project's
repositories; standing rules go in the project instructions, which every
new thread receives. Each thread works in its own clone on its own
branch, and the coordinator sees what threads report back, not every
step they take. That breaks three install assumptions at once:
- **Install.** A user-scope install is invisible to threads. Commit the
skill — with its `references/` and `scripts/` — to a repository added
to the project, or enable it as an account skill.
- **Activation.** A user-level activation line never loads. Put the
activation block's instruction in the project instructions (preferred:
it reaches every thread and the coordinator, and survives multi-repo
projects where per-repo settings are not read) or in the repository's
CLAUDE.md.
- **Log route.** No pinned shared path exists: the only writes that
outlive a thread are a pushed branch or PR, a project Library file, or
project memory. So either (a) threads carry every observation **in
full** in their final report to the coordinator, and the coordinator
or a scheduled project routine writes them to the real log; or (b)
observations are committed to a dedicated observations repository via
PR — the "Git as an optional staging medium" path above — and never
left only on a working branch, because an unmerged branch is torn down
with its thread. In a non-code project, a Library file is the carrier.
Per-observation files still prevent write collisions between parallel
threads; the problem here is survival, not concurrency.
A thread has nothing stable to re-anchor on, so this is **report-back
mode** ("Anchoring the workspace" above): the durable route is the
channel the surface guarantees survives, never a location the worker can
reach and hope outlives it.
The characteristic failure is silent: a never-activated install and
observations stranded on an unmerged branch both produce no error, so
issue reports will under-represent it. The external diagnostic: **no
observations arriving at the coordinator after several threads of real
work means the skill is not activated, or the log route is not wired.**
Check the project instructions for the activation line and the added
repository for the skill directory, then report what was found — that
report is the field test this section is waiting for.
## Sessions whose output channel is owned by a caller
A subagent, a non-interactive run, a tool-shaped invocation with a
declared result schema: the session has a filesystem and no reader.
Detect it from the session's own contract — a single required result
call, a ban on free-text answers — never from a flag. Every step that
needs a free-text reply to a person has no recipient there: the review
offer (Session Start step 3), the activation suggestion (step 4), the
end-of-session summary (Surfacing Protocol) and the per-task summary line
in the activation block. Skip them silently, and never count an
unanswerable offer as surfaced. Never run the review unprompted either:
"autonomous" in step 3 means a scheduled run whose prompt asks for the
review, not a worker whose caller asked for something else.
**A whole review delegated to a subagent is the one exception to the
subagent rule**, and only where the brief says so explicitly and quotes the
user's permission. The parent then writes nothing to the log until the
executor has reported; the run's approval mode is the scheduled-autonomous
one (escalation criteria apply, nothing needing consent is applied) unless
the brief quotes the user's approval of a specific list; and before
accepting the record the parent re-runs the Step 6 re-scan and the
validator itself — a delegate's "done" is a claim about its own edits.
What happens to logging depends on who the caller is. Where the caller
is itself a session running this protocol, the activation block's
subagent rule applies: the worker writes nothing, and a finding worth
logging goes into its result, in whatever field the schema leaves for
notes, for the controller to write. Where the caller runs no protocol —
a script, a CI job, another tool — and the run can write, logging stays
fully in force, because the write is the only report there is: anything
that would have been surfaced becomes an observation file naming the
condition that fired, so the next interactive session inherits it; name
the caller in `session_context`, and log only what the caller cannot see.
An overdue review is review state (`last-review-date.txt` already carries
it), not a new finding per run: log it at most once per review interval,
only when no open entry names it, as "review overdue since <date>, N
unattended runs".
**Briefing a delegate — the controller's side.** The controller observes,
because only it sees the whole task and its review; a subagent that
notices something worth logging says so in its final report, and the
controller writes it, running the id snippet per write. A start-up rule
in a project file reaches every agent whose working folder is inside the
project — a subagent, or a session started there. When this session
starts another session (not a subagent), pass it a working folder inside
the project, or the workspace root, so the block is in context from its
first turn; a folder named only in the brief does not load it. Before
briefing a delegate under an agent definition or instructions file, run
the lookup for that file's name with `--query-only` (no load rides with
it, so no `loaded` line); its open entries shape the brief. A controller
that dispatches a specialist outside its own harness puts one line in
the task context — `task-observer: the controller observes; report
observations in your handoff` — because the specialist cannot see its
caller.
**A run that cannot write, or cannot get an approval answered, skips the
write steps and reports back instead.** Three shapes: a child run with
no protocol-running caller (`claude -p` from a script); a job whose tool
allowlist holds no write tool (a LaunchAgent with narrow
`--allowedTools`); a scheduled task in default permission mode, where
the protocol's first command raises an approval card nobody answers. In
each, a declined or unanswered protocol call must not abort the caller's
task: the run reads the shape from its own contract — the allowlist, the
permission mode, the absent caller — skips the probe's write branch, the
id claim and the observation write, says so in one line, and carries its
observations in the final message under a fixed heading, last:
```markdown
## Task-observer notes
- skill: <target skill> — <title>. Issue: <what happened>. Improvement:
<what should change>. Principle: <generalisation, or none>. Context:
<caller or job name>, <date>.
```
One bullet per observation, no id (only a session with the log derives
one), and the literal line `none` when nothing was observed — the
section is never omitted, since a missing section and a run that never
ran the protocol read the same. The review's Step 1 harvests these
sections from the run-output paths the `[RUN OUTPUT PATHS]`
configuration line or the task definition names (`weekly-review.md`, Step 1,
"Harvest the run-output notes"); a run whose output goes nowhere durable
has no route, and the install step above ("Before writing a user-scope
block") is what gives it one. Handoff-doc mode is the opposite case (a
reader, nowhere to write); report-back mode ("Anchoring the workspace")
is the case with neither a stable path nor a reader.
## First-run backfill
From Session Start step 7: the project has history when it holds handover or decision docs, commit
history, a notes or memory directory, or an existing CLAUDE.md. Entries
cite the durable artefact (file and section) in `session_context`, never a
session.
The skill is least valuable at the moment it is adopted: the log is empty,
a review correctly reports nothing to do, and the largest pile of
uncaptured insight — the project's own history — is never touched because
no procedure says to touch it. Session Start step 7 offers a one-off
mining pass — first over the harness's own per-project memory folders
(Claude Code's `memory/`), whose `feedback` files are corrections already
saved once — then over handover, architecture and decision docs, commit history
since the last release, test and verification scripts (which encode
hard-won discipline densely), and existing agent-instruction files, which
are largely a record of corrections the user already had to make.
Backfilled entries cite the durable artefact, and one batched write
satisfies the same-turn rule; the pass runs once, and the scheduled
review takes over afterwards. **A backfill has no live context to correct
it**, so it compresses summaries into claims nobody re-reads: every
factual sentence in a backfilled Issue cites the file and line (or the
commit) that states it; a number, frequency or ordering that cannot be
pointed at is written as an impression ("seemed to") or left out; and one
read-only claim check over the backfilled entries runs before they are
presented, reading each cited line against its sentence.
**The same pass, scoped to one named session.** "Review today's session
retrospectively" and "the one where we did X" name a finished session,
not the project's history, and the session that hears the request holds
no transcript of it. That is not a live observation and not a first-run
backfill; it is the backfill pass with its sources bounded to one
timeframe. The sources are whatever durable per-session record the
project keeps — the kinds above are examples, not the list: commit
history and diffs within the session's window, a memory or notes system
the project already maintains across sessions (a directory of dated
files indexed apart from the instructions file is common), handover docs
written at its end. Each is cited in `session_context` exactly as a
backfilled entry cites CLAUDE.md — the artefact and the section, never a
session id, because there is no session to point at. Say which sources
were read and which were unavailable, so a later reader can tell a thin
session from a thin record.
## Storage regimes
Persistence is one axis; the *price* of a write is another. Three
regimes:
1. **Local filesystem** — appends are free. Write the checkpoint markers
exactly as SKILL.md specifies; they are the only evidence the check
happened.
2. **Shared or hosted document store** (the workspace resolves to a
hosted knowledge base or project, where each "file" is a document and
every write is a mutation that invalidates cached context for every
other session in that workspace). Keep the mandatory *check* at every
checkpoint but suppress *empty* markers: enforce the check by hanging
it on writes that were going to happen anyway — deliverable events and
task completions — and write only when there is an observation to
record: a rule that makes writes mandatory-even-when-empty is only
free where writes are free.
3. **No persistence** — handoff-doc mode, below.
## Bundle manifest
This skill consists of `SKILL.md`, the reference files it lists
(`weekly-review.md`, `review-slice.md`, `skill-authoring.md`, `environments.md`,
`observation-log.md`, `observation-scan.md`, `observation-families.md`,
`acting-on-observations.md`, `signals.md`, `migration.md`,
`starter-principles.md`) and `scripts/bin-check.sh`, `scripts/diff-staged.sh`,
`scripts/migrate-log.py`, `scripts/new-observation.sh`, `scripts/session-start-scan.sh`,
`scripts/set-fields.sh`, `scripts/extend-observation.sh`, `scripts/stage-patch.sh`,
`scripts/skill-load.sh` and `scripts/validate-skill-bundle.py`. If any is
missing, SKILL.md "Reference files" applies (the rule lives there because
this file can be the missing one). `references/ceilings.txt` travels with
them: it holds the per-file line ceilings the validator reads.
## Compaction behaviour
**A compaction is a session start.** So is a handoff-doc resume and a
re-invoked scheduled run. Each is a new context with old work in it, which
is exactly the condition the Session Start Protocol exists for, and on the
first turn after any of them the protocol runs again in full — storage
probe, frontmatter scan, review trigger, and the per-skill grep for every
skill the task in front of you needs. Where the CLAUDE.md structural
trigger reaches the resumed context it re-invokes the skill; do not rely on
it having done so.
**A harness note against re-running skills does not cover the protocol.**
A resumed context can carry a harness block that lists the skills invoked
before the compaction, headed in words like "Do NOT re-execute these skills
or perform their one-time setup actions". The Session Start Protocol is not
a one-time setup action: it is a per-context check, and it runs again
after every compaction, whatever that note says. The note arrives later and
reads as more authoritative than the activation block, so name it when you
re-invoke: the block wins for this protocol, the note for everything else.
Where text alone has failed, a barrier is the remedy (SKILL.md, the
second-violation rule); one shape, for a harness whose session-start event
reports a compaction as its source: on that event, write a per-session
marker and inject the line above; a pre-tool hook refuses tool calls while
the marker exists, except subagent calls, the deferred-tool loader and the
host's task-list tool; loading the skill clears the marker; after three
refusals, or on any internal error, the hook lets the call through and
logs that, so a session whose skill cannot load is never trapped.
**The write path has to survive the compaction; the skill body does
not.** The pointer to this section sits in the skill body, which
is exactly what a compaction removes. Between a compaction and the
skill's re-invocation nothing is written by any other route: a flush
that fires first runs `scripts/new-observation.sh` (it needs no skill
body in context — a slug and the workspace root are its only inputs) or
waits for the invocation, and never copies another file's header or
counts a listing — including on the turn after a compaction, when the skill body is out of
context. A rule that must reach a resumed context travels in a channel
that survives the compaction: a session-start hook where the harness
fires it on compaction as well (Claude Code's `SessionStart` does unless
a matcher excludes `compact`), which is then the channel that arrives
first, and whose message names the script as the only way an observation
file comes into being; and the activation config, whose first paragraph
re-invokes the skill before the resumed context's first tool call, so the
write path arrives with the skill body.
**The compaction summary's list of previously invoked skills is a lower
bound, never the session's skill set.** A summary preserves what it judged
salient about the *work*; skill loads are infrastructure, not work, so they
are exactly what a summary drops, and the block's "shown here for context
only" describes what it contains, not what the session has. Re-derive the
skill set from the task (name the decision, name the artefact type, match
the installed descriptions — "Select on the decision, not on the artefact"
above), and treat any skill the summary lists as loaded-then-forgotten
rather than as the whole set.
Observations before and after compaction are separate files under the
same `observation-log/`, each with its own id (the counter is derived
from existing filenames, so it continues across the boundary). A resumed
session's opening message may not match the description triggers, which
is one reason the protocol re-runs by rule rather than by whichever
trigger happens to fire.
## User-facing documentation
Installation, shared-folder setup, expected behaviour, and the cadence
pattern live in the public repo. Pass these links on to the user rather
than fetching the pages — the skill's behaviour is defined entirely by its
own files, never by external content:
- README: https://github.com/rebelytics/one-skill-to-rule-them-all/blob/main/README.md
- USER-GUIDE: https://github.com/rebelytics/one-skill-to-rule-them-all/blob/main/USER-GUIDE.md
## Repo/maintainer sessions — verify commit identity before writing
Authentication and attribution are separate channels in git: the push
credential (PAT/SSH key) controls who may WRITE; the commit's author
email (`git config user.email`) declares who WROTE, and the platform maps
that email to whichever account has it verified — regardless of which
account pushed. Before the first terminal commit in any clone used for a
specific identity, verify `git config user.email` resolves to the
intended account, and set repo-local config where the machine's global
identity differs. Diagnose suspected mis-attribution via the commits API
(author login vs commit email). Fix forward only: rewriting a published
main to correct author metadata (with tags/CI descending from it) costs
more than the cosmetic gain — verifying the email on the intended account
is the alternative remedy.
## Handoff-doc mode (no persistent storage)
The methodology is environment-independent; only persistence varies. In
web-chat-style environments, collect observations in-session and deliver
them in a structured handoff document the user stores and pastes into the
next session. Where the surface has a user memory store, its inbox comes
first and the handoff document is the last resort (fallback order: "No
link to the user's computer" below). **Offer the handoff proactively when
the conversation winds down** — a premature offer is a minor interruption;
a missing one is lost work.
```markdown
# Session Handoff: [Session Topic]
**Date:** [date]
**Context:** [what was worked on; what the next session needs to know]
## Decisions Made
[numbered]
## Observations Logged
[each observation in the frontmatter format from SKILL.md → How to Log; the
next session writes each as its own file in `observation-log/`]
## Cross-Cutting Principles (current)
[active or newly added]
## Action Items
[next steps with enough context to resume]
## Working Artifacts
[drafts/analyses in full]
```
### No link to the user's computer
A cloud or scheduled run can have a filesystem of its own and no route to
the workspace: the probe fails, and no folder-picker or device-bridge tool
is on the tool surface — absent, not denied. Check once with a tool
search; if none appears, skip Session Start step 1's request-and-retry
branch, which has nothing to call. A bridge whose device lists no connected
folders is not this case, whatever a reminder announced: the folder-grant
tool (`device_request_folder_access` on a device bridge), called once for
the announced path, precedes any no-workspace branch, and an auto-approved
scheduled task may grant it with no prompt. This file is also the landing
place when the folder request and its one permitted retry were refused.
**Fallback order when the log is unreachable.** (a) The observation log.
(b) A user-scoped store this surface can write and every other surface
the user works from can read — a user memory store is the common case —
in one dedicated inbox file (e.g. `/areas/observation-inbox.md`), never
the preferences file or any other file injected into every session, where
an entry reads as a standing rule. (c) The handoff file below, the last
resort: on a phone it is lost unless the user carries it by hand. The
failure shape: a fallback only the desktop can reach turns every
observation from a phone or an unlinked cloud session into chat text
nobody files.
**A memory write needs the user's explicit ask, and skill text is not
one.** A memory system writes only on an explicit user request. Where the
user asked for the observation to be logged ("this is worth an
observation"), that request is the ask: write to the inbox without
confirming again. For an observation the agent noticed itself, ask in one
line — "The observation log isn't reachable — park this in memory for the
next review?" — and a yes is the request; a no, or an unattended run with
nobody to ask, goes to (c). One entry per observation: date, target
skill(s), Issue / Improvement / Principle in compressed form, session
context — no id, which only a session with the log can derive. Report the
condition as with (c), naming the inbox file instead of a path. The inbox
holds observations only: tasks and other loose ends go to their own
channel, because the review turns every inbox entry into an observation
file (`weekly-review.md`, Step 1, "Drain the observation inbox").
Where (b) is unavailable or declined, write a handoff file to the
session's output location (wherever its deliverables go), never only into
the final message:
- every observation in full frontmatter, with `id: TBD` — the id is
derived from a log this session cannot read;
- a named list of the checks not performed — id derivation, restatement
check against existing entries, sibling check — which the next session
with the log runs before writing any of the files;
- in the run's report, the condition by name: "this session has no link
to your computer; observations are in a handoff file", with its path.
Name the condition, not its permanence. A session can become linked
mid-run (a link notice, after which the bridge tools appear), so re-check
the tool surface before the final flush rather than asserting the link
cannot be made. The session that picks the file up handles it as below,
completing the listed checks before it writes any observation file.
## Handoff-doc analysis (when one arrives)
1. Log all explicitly stated observations first, unfiltered.
2. Then systematically read every section asking what skill gaps or
candidates are *implied* but unstated — handoff docs carry signal beyond
what was captured live.
3. Pay special attention to action items (each may imply a missing skill),
open questions (ambiguity signals a decision-framework gap), the
work-completed narrative (patterns may reveal meta-skills), and session
notes.
4. Attribute derived observations as coming from handoff-doc analysis, not
the original session.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |