@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/skills/creating-skills/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: plastic-creating-skills
+description: >
+  Author or revise a Plastic skill, a subagent or Agent role file, or a
+  lifecycle hook with progressive disclosure. Use when creating or editing a
+  SKILL.md, writing a description or frontmatter, designing the slim body,
+  building references, evals, or scripts, or scaffolding a new skill. Also use
+  when a skill is too big or over its token budget, when prompts are bloated,
+  when an agent keeps missing a step or ignoring instructions, or when the user
+  says "progressive disclosure", "write a skill", "thin router", "split into
+  references", or "make this slim".
+---
+
+# Creating Skills
+
+Author skills, agents, and hooks as thin routers over deep references. This
+body carries the rules that must stay correct without opening anything, then
+routes each authoring task to the reference that holds the depth.
+
+## Rules (must be right even if no reference is opened)
+
+- Three load levels, hard budgets: metadata around 100 tokens (always loaded),
+  body under 5000 tokens and under 500 lines (loaded on trigger), references on
+  demand. Keep the body well under budget, not at the ceiling.
+- Progressive disclosure first: the body routes, the references hold the depth.
+  Any deep how-to in the body belongs in a reference instead.
+- Description states WHEN to use, not the workflow. Write it in third person,
+  front-load concrete trigger keywords, and include at least one indirect
+  trigger (a request that never names the domain). Never summarize the steps.
+- Bind every reference link to an observable trigger condition. Never leave a
+  bare pointer to a reference.
+- References stay one level deep. Any reference over 100 lines opens with a
+  table of contents.
+- Build at least three evals before writing extensive docs.
+- Match determinism to fragility: a deterministic script for fragile or
+  repeated mechanical steps, prose for judgment calls.
+- Imperative voice, no second person. No em-dashes or en-dashes in any shipped
+  skill or doc (use commas, periods, parentheses, colons).
+
+## Route the authoring task to its reference
+
+| Authoring task | Open |
+|---|---|
+| Starting any authoring task: load the load-level model and the thin-router pattern first | `references/progressive-disclosure.md` |
+| Authoring an Agent Skill (frontmatter, description, slim body, voice) | `references/skills.md` |
+| Authoring a subagent or Agent role file | `references/agents.md` |
+| Authoring a lifecycle hook | `references/hooks.md` |
+| Deciding script versus prose, or writing a script | `references/scripts.md` |
+| Building evals for a skill | `references/evals.md` |
+
+## Shrink context, or let a skill self-improve
+
+- When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for
+  the global token levers: a PostToolUse hook that trims noisy tool output before it enters
+  context, and Programmatic Tool Calling that keeps looped tool results in code, not context.
+- When a skill should learn from its own real runs, open `references/hooks.md` (E8) for the
+  propose-only Stop or SubagentStop loop (transcript to proposed edits to human approval to
+  git, effort-gated). The dedicated skill is the future `improving-skills` skill.
+
+## Scaffolder and evals
+
+- To start a new skill, agent, or hook from a born-slim file, run
+  `scripts/scaffold.rb`.
+- To design, run, and grade evals in depth (paired runs, assertions after
+  observing, pass rates), use the `plastic-evaluating-skills` skill.

package/skills/creating-skills/evals/evals.json

@@ -0,0 +1,108 @@
+{
+  "skill_name": "plastic-creating-skills",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to author a new Plastic skill, how should I structure it?",
+      "expected_output": "The skill should activate. This is a direct authoring request that names the domain. Guide the user through progressive disclosure: metadata around 100 tokens, a slim body under 5000 tokens and 500 lines that routes, and references on demand. Point to references/skills.md for frontmatter, description, and voice, and route load-level questions through references/progressive-disclosure.md first.",
+      "files": [],
+      "assertions": [
+        "The skill activates (direct authoring request that names the domain).",
+        "The response routes to references rather than dumping deep how-to inline.",
+        "The response states the load-level budgets (around 100 token metadata, body under 5000 tokens and 500 lines)."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The agent keeps ignoring my instructions and the file is huge, help me restructure it",
+      "expected_output": "The skill should activate. This is an indirect trigger that never names skills or progressive disclosure, but the symptoms (bloated file, agent missing or skipping steps) are exactly the over-budget body case the skill covers. Guide toward splitting the body into references, keeping the body a thin router, and binding each reference to an observable trigger condition.",
+      "files": [],
+      "assertions": [
+        "The skill activates on the indirect trigger (no skill or progressive-disclosure keyword in the prompt).",
+        "The response guides toward splitting the body into references and keeping a thin router."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Scaffold a new lifecycle hook for Plastic",
+      "expected_output": "The skill should activate. Authoring a lifecycle hook is in scope. Route to references/hooks.md and offer scripts/scaffold.rb to start the hook from a born-slim file.",
+      "files": [],
+      "assertions": [
+        "The skill activates (authoring a lifecycle hook is in scope).",
+        "The response routes to references/hooks.md and offers scripts/scaffold.rb."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Our prompts are bloated and we keep blowing the context budget",
+      "expected_output": "The skill should activate. This is an indirect trigger: the user describes bloated prompts and a context budget problem without naming skills. The skill restructures instructions into a thin router over deep references with hard load-level budgets, which is the fix for this symptom.",
+      "files": [],
+      "assertions": [
+        "The skill activates on the indirect context-budget trigger (no skill keyword in the prompt).",
+        "The response treats the fix as a thin router over deep references with hard load-level budgets."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Run the evals on my skill and check the pass rate",
+      "expected_output": "The skill should NOT trigger. Running evals and reading pass rates is the job of plastic-evaluating-skills, not authoring. Near-miss negative: shares the words 'skill' and 'evals' but the operation is grading an existing skill, not creating or revising one.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (running and grading evals is plastic-evaluating-skills, not authoring)."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Create a new intent for the dashboard work",
+      "expected_output": "The skill should NOT trigger. Creating an intent is plastic-creating-intent. Near-miss negative: shares the verb 'create' but the object is an intent, not a skill, agent, or hook.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (creating an intent is plastic-creating-intent)."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "I keep losing every team fight because of a skill issue in this game, any tips?",
+      "expected_output": "The skill should NOT trigger. This is a gaming question with no relation to authoring instructions. Near-miss negative: shares the word 'skill' in an unrelated sense.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (gaming question, unrelated sense of 'skill')."
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "Write unit tests for my Ruby model that validates email addresses",
+      "expected_output": "The skill should NOT trigger. Writing test code is a Ruby testing task. Near-miss negative: shares 'write' and 'test' but has nothing to do with authoring a skill, agent, or hook.",
+      "files": [],
+      "assertions": [
+        "The skill does not activate (writing test code is a Ruby testing task, not authoring a skill)."
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "Author a slim SKILL.md for a PDF-extraction skill",
+      "expected_output": "Activation is assumed for this output-quality case. Correct output is a SKILL.md whose frontmatter description is third person, front-loads concrete trigger keywords, states WHEN to use rather than the workflow, and includes at least one indirect trigger. The body stays under 5000 tokens and under 500 lines and routes to references rather than carrying deep how-to. Each reference link names an observable trigger condition with no bare pointer like 'see references/'. References stay one level deep, and no string contains an em-dash or en-dash.",
+      "files": [],
+      "assertions": [
+        "The frontmatter description is written in the third person (no 'you' or 'I').",
+        "The description front-loads concrete trigger keywords in its opening clause.",
+        "The description includes at least one indirect trigger (a symptom phrasing that never names PDF extraction or skills).",
+        "The body is under 5000 tokens and under 500 lines.",
+        "Every reference link is bound to an observable trigger condition (no bare pointer such as 'see references/').",
+        "References stay one level deep (no reference points to a deeper reference).",
+        "No string in the SKILL.md or its references contains an em-dash or en-dash."
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "Make this subagent role file slim, the description is vague and the body is too long",
+      "expected_output": "The skill should activate. Authoring or revising a subagent or Agent role file is in scope, and the symptoms (vague description, over-long body) are the progressive-disclosure case. Route to references/agents.md, tighten the description to state WHEN, and move depth into references. Output should keep the body under budget and use no em-dashes.",
+      "files": [],
+      "assertions": [
+        "The skill activates (revising a subagent or Agent role file is in scope).",
+        "The response routes to references/agents.md and tightens the description to state WHEN.",
+        "The proposed output keeps the body under budget and uses no em-dash or en-dash."
+      ]
+    }
+  ]
+}

package/skills/creating-skills/references/agents.md

@@ -0,0 +1,168 @@
+# Authoring an Agent (subagent)
+
+How to write a subagent / Agent role file: scope, tools, description, the reviewer pattern,
+collector discipline, and the skill-vs-agent decision. Rules cite section D of the
+best-practices standard (D1 through D6).
+
+## Contents
+
+- [When a skill suffices vs escalate to an agent](#when-a-skill-suffices-vs-escalate-to-an-agent)
+- [The agent definition fields](#the-agent-definition-fields)
+- [One focused task per agent](#one-focused-task-per-agent)
+- [Tight tool set](#tight-tool-set)
+- [Description: embedded when-to-use examples](#description-embedded-when-to-use-examples)
+- [Collectors, not implementers](#collectors-not-implementers)
+- [Reviewer / devil's-advocate agents](#reviewer--devils-advocate-agents)
+- [Composing skills and agents](#composing-skills-and-agents)
+- [Self-checks](#self-checks)
+
+For load levels, the three-bucket model, and description-as-trigger rules, open
+`progressive-disclosure.md` and `skills.md`. Do not re-derive them here (C7).
+
+## When a skill suffices vs escalate to an agent
+
+Decide before authoring an agent at all. A full agent carries its own context window and tool
+grant, so it is too heavyweight for quick work [D5].
+
+| Situation | Build | Why |
+| --- | --- | --- |
+| Light read-only check, single-file validation, scaffold one file | Skill | A skill loads on trigger and runs in the current context, no spin-up cost [D5] |
+| Deep multi-file audit, parallel investigation, isolated noisy work | Agent | The isolated context keeps search and log noise off the main thread [D2][D5] |
+| Same task repeated with deterministic steps | Script (see `scripts.md`) | Executed, not loaded; token-free and variance-free |
+
+Default to a skill. Escalate to an agent only when the work needs an isolated context budget or
+its own restricted tool grant.
+
+## The agent definition fields
+
+An agent file is frontmatter plus a system-prompt body. Set each field for one reason.
+
+| Field | When it matters | Set it to |
+| --- | --- | --- |
+| `name` | Always. The orchestrator and `SendMessage` address the agent by it | Lowercase-hyphen, one capability (`spec-reviewer`, `dependency-auditor`) |
+| `description` | Always. The orchestrator delegates purely on this text [D3] | Trigger conditions plus embedded when-to-use example pairs (see below) |
+| `tools` | Always. Omitting it grants every tool, which over-arms the agent [D1] | Only the tools the one task needs |
+| `model` | When the task is cheap (Haiku) or hard (Opus) | The cheapest tier that holds quality |
+| `proactive` marker | When the agent should auto-fire without an explicit ask [D3] | Include "use proactively" inside the description |
+
+Keep the body in imperative voice. State the agent's single job, its numbered process, and its
+output contract. Push reference detail into files the agent reads on demand, same as a skill body.
+
+## One focused task per agent
+
+Give each agent exactly one task. Focused scope plus a tight tool set is what makes delegation
+decidable and cheap [D1].
+
+1. Name the single responsibility in one phrase. If the name needs "and", split into two agents.
+2. Start with one agent. Add a specialist only when it materially improves isolation or tool
+   scoping [D1]. More agents widen the discovery surface and the orchestrator's choice space.
+3. Write the body around that one task. An agent that "reviews and also fixes and also reports" has
+   three jobs and no clear output contract.
+
+## Tight tool set
+
+Grant only the tools the one task requires [D1].
+
+| Agent kind | Typical tools | Excluded |
+| --- | --- | --- |
+| Reviewer / auditor | Read, Grep, Glob | Edit, Write, Bash (read-only by design) [D4] |
+| Collector / researcher | Read, Grep, Glob, WebFetch | Edit, Write (returns a summary, does not change code) [D2] |
+| Implementer | Read, Edit, Write, Bash | Only the surface its task touches |
+
+A reviewer with Edit can rewrite the code it judges. A collector with Write can leak its noisy
+context back into the tree. The tool list is the guardrail; keep it narrow.
+
+## Description: embedded when-to-use examples
+
+The orchestrator never reads the body at delegation time. It routes on the description alone, so
+the description must teach the boundary by example [D3].
+
+Write the description with:
+
+1. A trigger clause in third person ("Use when reviewing a spec before the plan stage").
+2. One or more `<example>` pairs showing a matching prompt, the assistant's choice to delegate, and
+   a one-line `<commentary>` on why. Example pairs teach the boundary a keyword list cannot [D3].
+3. "use proactively" when the agent should auto-fire without the user naming it [D3].
+
+Concrete shape:
+
+```
+description: >
+  Use when a spec is complete and needs an adversarial review before planning.
+  Use proactively after the spec-specialist writes spec.md.
+  <example>
+    Context: spec.md just landed for the active intent.
+    user: "Is this spec ready to plan?"
+    assistant: "I'll use the spec-reviewer agent to challenge the spec before planning."
+    <commentary>Adversarial review runs at the Why-to-How boundary.</commentary>
+  </example>
+```
+
+A description that summarizes the agent's workflow instead of its trigger makes the orchestrator
+act on the summary and skip the body. State when to fire, not how the agent works.
+
+## Collectors, not implementers
+
+Use a subagent as an information collector that returns a short summary, not as an implementer [D2].
+
+| Do | Avoid |
+| --- | --- |
+| Return a tight summary: findings, file paths, a verdict | Stuffing raw search output or full file dumps back into the main thread |
+| Write a plan or summary markdown file as shared memory; have the main thread read it [D2] | Passing large results inline, which defeats the isolation |
+| Keep search, log, and crawl noise inside the agent's own context [D2] | Re-emitting that noise to the orchestrator |
+
+The reason a subagent has an isolated context is to absorb noise. The filesystem (a plan or summary
+file) is the shared memory between agents; the agent's return value is the headline, not the
+transcript [D2].
+
+## Reviewer / devil's-advocate agents
+
+A reviewer agent needs four things, or it produces unscoped, unverifiable results [D4].
+
+1. Read-only tools: Read, Grep, Glob, and nothing that edits [D4]. A reviewer that can edit stops
+   being a reviewer.
+2. A numbered review process in the body, so every run covers the same checks in the same order.
+3. Explicit anti-scope: a "do not use for" clause that names what the agent must not do (implement
+   fixes, refactor, approve its own changes) [D4].
+4. A fixed, severity-bucketed output format, so findings are comparable across runs [D4].
+
+Fixed output contract:
+
+```
+## Critical
+- <finding> (file:line) -> <why it blocks>
+
+## Major
+- <finding> (file:line) -> <impact>
+
+## Minor
+- <finding> (file:line) -> <suggestion>
+
+## Verdict
+PASS | BLOCK, with one-line reason.
+```
+
+The severity buckets and the verdict are mandatory. Empty buckets stay in, marked "none", so a
+reader can tell the agent checked.
+
+## Composing skills and agents
+
+Two mechanisms load content into an agent's context. Choose by what budget the isolated agent
+should carry [D6].
+
+| Mechanism | Effect | Use when |
+| --- | --- | --- |
+| Subagent `skills:` | Preloads the full skill content into the agent at spawn [D6] | The agent must always have that skill's rules in hand |
+| Skill `context: fork` | Runs the skill body as a task prompt inside a chosen agent type [D6] | A skill should execute as an isolated agent, not inline |
+
+Pick deliberately. `skills:` spends the agent's budget up front for guaranteed availability;
+`context: fork` hands the body to a fresh agent so the work runs isolated [D6].
+
+## Self-checks
+
+- Could this be a skill instead? If the work is light or single-file, build a skill [D5].
+- Does the agent have exactly one job, named without "and"? [D1]
+- Is the tool list the minimum the job needs, and read-only for a reviewer? [D1][D4]
+- Does the description carry at least one `<example>` pair and "use proactively" if it auto-fires? [D3]
+- Does the agent return a summary and use a file as shared memory, not dump its context? [D2]
+- Does a reviewer have a numbered process, an anti-scope clause, and a severity-bucketed output? [D4]

package/skills/creating-skills/references/evals.md

@@ -0,0 +1,41 @@
+# Evals (author-time gate)
+
+This is the gate, not the method. It states the eval decisions an author makes while building a
+skill, then hands the full procedure to one place. Do not duplicate that procedure here.
+
+## Build evals before docs
+
+Build at least three evals before writing extensive documentation. A skill without an eval is an
+assertion, not a capability, so the eval forces the skill to close a real observed gap instead of an
+imagined one. [F1]
+
+Build RED-GREEN-REFACTOR. Run the scenario without the skill and record the verbatim failure (RED),
+write the minimal instructions that fix exactly that failure (GREEN), then close the loopholes the
+failure exposed (REFACTOR). Only instructions that move a failing eval earn their tokens. [F2]
+
+## What each eval must cover
+
+- Description triggering. Pair should-trigger queries with near-miss negatives: prompts that share
+  keywords with the skill but need a different skill entirely. Near-miss negatives catch
+  over-triggering, the most common description failure. State the trigger set here; do not size the
+  query count or split here. [F3]
+- Output quality. Write assertions only after observing real output. Make them specific, verifiable,
+  and countable, with no benefit of the doubt and no brittle exact-phrase matching. Assertions
+  written before observation encode hopes, not behavior, so include at least one output-quality case
+  graded this way. [F4]
+- Discipline under pressure. For a skill whose job is restraint, stack pressures (time, sunk cost,
+  authority, exhaustion) with forced options and run the case via a subagent. Reciting the rule is
+  not complying with it. [F5]
+
+## Grading and reliability decisions
+
+Grade with the cheapest sufficient tier, and track capability (pass@k) separately from reliability
+(pass^k) with k at least three. The evaluating-skills skill owns the grader taxonomy, judge
+calibration, clean-context execution, and cross-model testing. [F6, F7, F8]
+
+## Run them with the methodology skill
+
+Use the evaluating-skills skill to author and run the evals. It owns the full method: eval scope
+selection, the query-count and train/validation protocol, the grader taxonomy and judge calibration,
+the iteration loop, and graduation of stable capability evals into regression. It is the source of
+truth for those steps; this file states the author-time gate and stops there. [F6, F7, F8]

package/skills/creating-skills/references/hooks.md

@@ -0,0 +1,248 @@
+# Authoring a Lifecycle Hook
+
+A hook is a harness: deterministic code the Claude Code runtime fires at a lifecycle
+event. Author one when a probabilistic skill keeps dropping a behavior and that behavior
+must hold every time.
+
+For body voice, budgets, and reference rules, see `progressive-disclosure.md` and `skills.md`.
+For deciding script versus prose and writing the handler logic, read `scripts.md` when the
+handler grows past a few lines. This file covers only hook authoring.
+
+## Contents
+
+- When to reach for a hook (E1)
+- The event to matcher to handler model (E2)
+- Which event for which job (E2)
+- Path rules and executability (E3)
+- No-op by default, opt-in (E4)
+- Exit codes and output channels (E5)
+- Verify the harness engaged (E6)
+- Token levers: global hooks that shrink context (E7)
+- Propose-only self-improving loop (E8)
+- Authoring checklist
+
+## When to reach for a hook (E1)
+
+Reach for a hook only after a skill has lost the behavior. The documented order is: first
+strengthen the skill description and instructions so the model keeps preferring the skill;
+if it still drops the step, enforce it deterministically with a hook. [E1]
+
+Test: ask "does this behavior have to hold even when the model forgets the skill?" If yes
+(a gate before a destructive tool, a savepoint before compaction, a format pass after every
+edit), the runtime must enforce it, not the prompt. If no, leave it in the skill body and
+spend no hook tokens on it. [E1]
+
+A hook is code on the critical path of an event. It is not loaded into context, so it costs
+no tokens at trigger time, but a mistuned hook blocks real work. Make it earn the
+intervention. [E1]
+
+## The event to matcher to handler model (E2)
+
+Hooks are configured in three nested levels: event, then matcher group, then handler list.
+[E2]
+
+- Event: the lifecycle moment (for example PreToolUse, SessionStart, PreCompact).
+- Matcher: which instances of that event fire the handler. For tool events the matcher is a
+  tool-name pattern (`Bash`, `Edit|Write`, `mcp__memory__.*`). For SessionStart the matcher
+  is a source (`startup`, `resume`, `clear`, `compact`). For PreCompact it is `manual` or
+  `auto`.
+- Handler: what runs. Handler types include `command` (a script, JSON arrives on stdin),
+  `http`, `mcp_tool`, `prompt` (an LLM yes/no), and `agent`. Author `command` handlers as
+  scripts unless a non-script handler is clearly required. [E2]
+
+Each event exposes different inputs and a different blocking power, so the wrong event cannot
+do the job no matter how the handler is written. Select the event first, then the matcher,
+then the handler. [E2]
+
+## Which event for which job (E2)
+
+| Job | Event | Matcher example | Can block | Key inputs |
+| --- | --- | --- | --- | --- |
+| Gate or validate before a tool runs | PreToolUse | `Edit\|Write`, `Bash` | yes (exit 2 or `permissionDecision: deny`) | `tool_name`, `tool_input` |
+| Format, lint, or remind after a tool succeeds | PostToolUse | `Edit\|Write` | block before next model call only | `tool_name`, `tool_input`, `tool_output` |
+| Boot or inject context at session start | SessionStart | `startup`, `resume`, `clear`, `compact` | no | `source` |
+| Savepoint before compaction | PreCompact | `manual`, `auto` | no (savepoint; exits 0) | compaction trigger |
+| Erase or augment a prompt before processing | UserPromptSubmit | (none) | yes (exit 2) | `prompt`, `permission_mode` |
+
+Notes that change the choice of event: [E2]
+
+- PreToolUse fires before the tool runs and can stop it. Use it for gates and pre-act
+  validation (block an edit to project code before the plan exists, block a destructive
+  Bash command).
+- PostToolUse fires after the tool has already run. It cannot undo the tool. Use it to format
+  the result, lint it, or surface a reminder, and to block the next model call when the
+  output is unacceptable.
+- SessionStart cannot block. Use it to inject boot context, not to enforce anything. Its
+  stdout on exit 0 becomes conversation context (see exit codes).
+- PreCompact fires before the runtime compacts the conversation. Use it to write a savepoint
+  while the full context still exists.
+
+Plastic ships working instances of each: `scripts/hook-code-gate` (PreToolUse gate),
+`scripts/hook-session-start` (SessionStart boot and inject), `scripts/hook-savepoint-pre`
+(PreCompact savepoint). Read one before authoring a new hook of the same shape.
+
+## Path rules and executability (E3)
+
+Two failures here are silent: the hook never fires and nothing reports why. [E3]
+
+- Reference the handler script through the exported placeholders: `${CLAUDE_PLUGIN_ROOT}` for
+  a script shipped inside a plugin, `${CLAUDE_PROJECT_DIR}` for a script that lives in the
+  project. A relative path resolves against an unpredictable working directory; a hard-coded
+  absolute path works in development and breaks on another machine. [E3]
+- Make the script executable: `chmod +x` the handler file and commit that bit. A
+  non-executable `command` handler fails silently. [E3]
+- Give the script a shebang (`#!/usr/bin/env ruby` for Plastic hooks; any shell must run under
+  macOS /bin/bash 3.2). [E3]
+
+Other placeholders the runtime exports: `${CLAUDE_PLUGIN_DATA}`. [E3]
+
+## No-op by default, opt-in (E4)
+
+Make a hook a no-op by default and enable it only through explicit config. Exit 0 (allow,
+emit nothing) unless the user has opted in. A reminder or validation hook that fires for users
+who never enabled it blocks or noises work that was never asked for. [E4]
+
+Concrete shape of an opt-in, no-op-by-default handler:
+
+```ruby
+#!/usr/bin/env ruby
+# PostToolUse reminder. No-op unless explicitly enabled.
+require "json"
+config = ENV["CLAUDE_PROJECT_DIR"] ? File.join(ENV["CLAUDE_PROJECT_DIR"], ".myhook.yml") : nil
+exit 0 unless config && File.exist?(config)   # opt-in gate: silent allow when not enabled
+payload = JSON.parse($stdin.read) rescue {}
+# ... emit reminder only past this point ...
+exit 0
+```
+
+The early `exit 0` is the opt-in gate. Place the enable check before any side effect. [E4]
+Plastic gate hooks follow the same fail-open discipline: no bridge resolved means exit 0
+(allow), seen in `scripts/hook-code-gate`.
+
+## Exit codes and output channels (E5)
+
+The exit code, not the script's intent, decides what the runtime does with the output. [E5]
+
+| Exit code | Meaning | Where output goes |
+| --- | --- | --- |
+| 0 | success | stdout shown; for UserPromptSubmit and SessionStart, stdout becomes conversation context |
+| 2 | blocking error | stdout and JSON ignored; stderr fed back to Claude; blocks the action on events that support blocking |
+| other non-zero | non-blocking error | first stderr line in transcript, full text in debug log; action proceeds |
+
+Rules that follow from the table: [E5]
+
+- To inject context (SessionStart boot banner, UserPromptSubmit augmentation), exit 0 and
+  write the context to stdout. On those two events stdout is consumed as context, not just
+  displayed.
+- To block (a gate that refuses an edit, a validator that rejects a command), exit 2 and write
+  the reason to stderr. The agent reads stderr and can act on it. Plastic gates do exactly
+  this: `$stderr.puts "PLASTIC GATE - <reason>"; exit 2`.
+- For PreToolUse, prefer the structured decision over a bare exit. Emit
+  `hookSpecificOutput.permissionDecision` with value `allow`, `deny`, `ask`, or `defer`, plus
+  `permissionDecisionReason`. Do not use the deprecated top-level `decision` field. [E5]
+- Blocking with exit 2 works only on events that support it. PreToolUse is the clear gate
+  event; UserPromptSubmit, Stop, SubagentStop, and a few task events also support exit-2
+  blocking. SessionStart and SessionEnd cannot block; exit 2 there does not stop anything.
+  PreCompact runs a savepoint, not a gate (see the job table). [E5]
+
+PreToolUse JSON shape:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Plan not yet written; edits to project code are gated."
+  }
+}
+```
+
+`hookSpecificOutput` requires `hookEventName`. [E5]
+
+## Verify the harness engaged (E6)
+
+A hook that is configured is not a hook that ran. Verify engagement before relying on a hook
+to hold a behavior. [E6]
+
+The known failure: in background sessions the session-id environment variable can be unset, so
+hooks that resolve their state through the session (Plastic gates and savepoints resolve a
+per-session bridge) silently no-op. The work proceeds ungated and nothing reports it. [E6]
+This claim is grounded mainly in Plastic's own operation rather than independent reports; treat
+it as Plastic-specific until confirmed elsewhere (LOW-EVIDENCE per E6).
+
+Verify by observation, not assumption: [E6]
+
+- Trigger the event and confirm the side effect (the gate blocked, the savepoint file appeared,
+  the boot context showed). Absence of an error is not proof the hook ran.
+- Check the session-id environment variable is set in the context where the hook must fire;
+  if it is unset, session-scoped hooks no-op.
+- For a gate, attempt the action the gate should block and confirm it is refused. A gate that
+  never refuses in testing is a gate that is not engaged.
+
+## Token levers: global hooks that shrink context (E7)
+
+Progressive disclosure trims what a skill loads. Two GLOBAL hooks trim what tool traffic
+costs at runtime, independent of any skill body. Both are token-reduction levers. Reach for
+them when prompts or tool output blow the context budget. [E7]
+
+- PostToolUse output preprocessing. Register a GLOBAL PostToolUse hook that trims noisy tool
+  output before it enters context: collapse repeated lines, cut a thousand-line log to its
+  head and tail, strip ANSI control codes, drop progress chatter. The model never sees the
+  noise, so it never pays tokens for it. Scope the hook with a matcher over the loud tools
+  (for example `Bash`), keep it lossless on signal (trim volume, never the line that carries
+  the answer), and make it no-op by default per E4. This is one GLOBAL hook, not a per-skill
+  or frontmatter hook. [E7]
+- Programmatic Tool Calling. When a tool runs in a loop and only the final result matters,
+  keep the intermediate results in code and return just the answer, instead of letting every
+  call land in context. Reach for it when a skill drives a tool in a loop and the per-call
+  output is throwaway. Pointer only: this is a Claude Code runtime feature, not a hook you
+  author here. [E7]
+
+The first lever trims output already produced; the second avoids producing the context at
+all. Pair either with sub-agent isolation (see `agents.md`) when a whole noisy sub-task can
+run off to the side and return only its conclusion. [E7]
+
+Both levers cut the CONTEXT axis (the input the model reads). The model's own OUTPUT tokens
+(what it writes) are a separate axis with no hook: cut them with terse instructions, tool
+responses that offer a concise mode, and sub-agent offloading that returns a short summary
+instead of the full trace. [E7]
+
+## Propose-only self-improving loop (E8)
+
+A skill can learn from its own real runs without ever editing itself unattended. Reach for
+this shape when a skill should improve from what actually happened in its runs. [E8]
+
+Wire a GLOBAL Stop or SubagentStop hook that, once an effort threshold is met, reads the
+just-finished transcript, drafts proposed edits to the skill, and stops. A human reviews the
+proposal, approves it, and the approved change lands in git. The hook never writes the skill
+directly. [E8]
+
+The guardrails that make this safe: [E8]
+
+- Propose only. The hook emits a diff or a suggestion, never an applied edit. Approval is a
+  human step, so a bad proposal costs a review, not a regression.
+- Effort-gated. Run the analysis only past a threshold (a long enough transcript, a real
+  failure observed), so cheap runs spend nothing.
+- Git-landed. The approved edit goes through the normal commit path, so every
+  self-improvement is reviewable and revertible.
+- Global, not scoped. This is one GLOBAL Stop or SubagentStop hook, not a per-skill
+  frontmatter hook.
+
+Pointer only. The real self-improving skill is the future `improving-skills` skill; this
+section records the safe shape so a skill author knows the loop exists and keeps it
+propose-only. [E8]
+
+## Authoring checklist
+
+- [ ] Behavior must hold deterministically; a stronger skill description was tried first (E1).
+- [ ] Event chosen for its inputs and blocking power; matcher scopes it; handler is a script
+      unless another handler type is required (E2).
+- [ ] Script referenced through `${CLAUDE_PLUGIN_ROOT}` or `${CLAUDE_PROJECT_DIR}`, has a
+      shebang, and is `chmod +x` (E3).
+- [ ] No-op by default; the opt-in check runs before any side effect; exits 0 when not enabled
+      (E4).
+- [ ] Exit codes deliberate: 0 to allow or inject context, 2 to block with the reason on
+      stderr; PreToolUse uses `hookSpecificOutput.permissionDecision`, not top-level `decision`
+      (E5).
+- [ ] Engagement verified by triggering the event and observing the side effect, including the
+      unset-session-id no-op case (E6).