@zalom/plastic 1.0.0-beta.19 → 1.0.0-beta.20

package/PLASTIC.md

@@ -348,5 +348,5 @@ Detailed conventions live inside the skills that use them, not in this file.
 | Index maintenance | `plastic-managing-index` | — |
 | Releases, deprecations | `plastic-releasing` | deprecation process |
 | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
-| Writing agent instructions | `plastic-writing-instructions` | agentskills.io spec |
+| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
 | Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |

package/agents/plastic-enforcer.md

@@ -30,7 +30,7 @@ You are the Plastic Enforcer. You ARE the auto orchestrator, spanning the whole
 
 ## Constraints
 
-- Enforce gates manually; do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in headless or background runs
+- Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs
 - You never delegate gate ownership; the orchestrator is always the gate-keeper
 - Roles are thin handoff contracts, not an execution engine; dispatch through `plastic-executing-plan` by default, and through the superpowers skills only when they are available or the user prefers them
 - Fall back by case: if the harness supports subagents but superpowers is absent, use the native `plastic-executing-plan` engine; if the harness has no subagent dispatch at all, fall back to a single agent walking the full cycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.20",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-auto-arm

@@ -26,7 +26,7 @@ if triggered
 end
 
 # --- 2. Standing gate reminder when armed and pre-How ---
-bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_SESSION_ID"], cwd: Dir.pwd)
+bridge_data = Bridge.discover_bridge(session: ENV["CLAUDE_CODE_SESSION_ID"], cwd: Dir.pwd)
 if bridge_data && bridge_data.dig("build", "auto") == true
   intent = bridge_data["intent"] || {}
   store = intent["store"]; dir = intent["dir"]

package/scripts/hook-bash-gate

@@ -28,9 +28,9 @@ exit 0 if command.nil? || command.to_s.strip.empty?
 cwd = payload["cwd"]
 cwd = Dir.pwd if cwd.nil? || cwd.to_s.empty?
 
-# --- Load bridge (shared resolution; stdin session_id -> env -> /tmp scan) ---
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 session = payload["session_id"]
-session = ENV["CLAUDE_SESSION_ID"] if session.nil? || session.to_s.empty?
+session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.to_s.empty?
 bridge_data = Bridge.discover_bridge(session: session, cwd: cwd)
 exit 0 unless bridge_data
 

package/scripts/hook-code-gate

@@ -18,9 +18,9 @@ require_relative "lib/bridge"
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
-# --- Load bridge (shared resolution; stdin session_id -> env -> /tmp scan) ---
+# --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 exit 0 unless bridge_data
 

package/scripts/hook-create-gate

@@ -9,8 +9,8 @@
 # the on-disk file (which does not exist yet at PreToolUse), using IntentValidator
 # for born-complete frontmatter plus the sanctioned section structure.
 #
-# It depends ONLY on the stdin path + content, never on the auto-bridge or
-# CLAUDE_SESSION_ID, so it runs unconditionally (headless / background sessions).
+# It depends ONLY on the stdin path + content, never on the auto-bridge or any
+# session id, so it runs unconditionally (headless / background sessions).
 # It validates ONLY the intent file, never sentinel placeholder lifecycle files
 # (spec.md/plan.md/etc.); the path matcher excludes them.
 #

package/scripts/hook-gate-check

@@ -13,7 +13,7 @@ require_relative "lib/intent_validator"
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
 
-session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
+session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
 file_path_abs = File.expand_path(file_path)
 

package/scripts/hook-session-start

@@ -48,7 +48,7 @@ bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
   intent_dir = "#{store_root}/store/#{dir_name}"
-  session = ENV["CLAUDE_SESSION_ID"] || Process.pid.to_s
+  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
   bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)

package/scripts/lib/bridge.rb

@@ -61,19 +61,17 @@ module Bridge
     "auto-" + Digest::SHA256.hexdigest("#{store}/#{intent_id}")[0, 10]
   end
 
-  # Resolve a bridge session: first non-empty of explicit, CLAUDE_SESSION_ID,
+  # Resolve a bridge session: first non-empty of explicit (the stdin session_id),
   # CLAUDE_CODE_SESSION_ID, then a derived key. Never returns nil/empty.
   # Whitespace-only counts as empty.
   #
-  # The CLAUDE_CODE_SESSION_ID fallback (intent 79) is additive: it only changes
-  # behavior when CLAUDE_SESSION_ID is blank but CLAUDE_CODE_SESSION_ID is set —
-  # the bg/headless case where the real session id lives in CLAUDE_CODE_SESSION_ID.
-  # Keying by the real id (instead of a derived hash) lets the statusline, which
-  # receives that same id on stdin, find the bridge by direct filename lookup.
+  # The CLAUDE_CODE_SESSION_ID fallback (intent 79) carries the bg/headless real
+  # session id (Claude Code passes session_id on stdin, not via an env var; the
+  # headless id lives in CLAUDE_CODE_SESSION_ID). Keying by the real id (instead of
+  # a derived hash) lets the statusline, which receives that same id on stdin, find
+  # the bridge by direct filename lookup.
   def self.resolve_session(explicit, intent_id:, store:)
     return explicit.to_s.strip unless blank?(explicit)
-    env = ENV["CLAUDE_SESSION_ID"]
-    return env.to_s.strip unless blank?(env)
     code_env = ENV["CLAUDE_CODE_SESSION_ID"]
     return code_env.to_s.strip unless blank?(code_env)
     derive_key(store, intent_id)
@@ -591,7 +589,7 @@ module Bridge
   # (mid-session intent creation). Re-derives intent state, then sets build.auto.
   def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
     key = resolve_session(session, intent_id: intent_id, store: store)
-    if blank?(session) && blank?(ENV["CLAUDE_SESSION_ID"]) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
+    if blank?(session) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
       $stderr.puts "plastic: no session id available; arming auto with derived bridge key #{key}"
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)

package/skills/auto/SKILL.md

@@ -50,10 +50,10 @@ Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plasti
 `<dir>` (the `ID--slug` directory), and `<name>`. The first argument is the session id you
 want the bridge keyed by: pass the hook stdin `session_id` when you have it, otherwise
 `ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. `arm_auto` calls `resolve_session`, which
-picks the first non-empty of: the explicit id you pass -> `CLAUDE_SESSION_ID` ->
-`CLAUDE_CODE_SESSION_ID` -> a deterministic derived key (a hash of the store and intent id).
+picks the first non-empty of: the explicit id you pass -> `CLAUDE_CODE_SESSION_ID` -> a
+deterministic derived key (a hash of the store and intent id).
 It never returns nil, so the gate engages even when every session env var is empty; the call
-never needs a non-empty `CLAUDE_SESSION_ID` to function. Arming prints a one-line notice to
+never needs a non-empty session env var to function. Arming prints a one-line notice to
 stderr when it falls through to the derived key.
 
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the

package/skills/creating-skills/SKILL.md

@@ -0,0 +1,56 @@
+---
+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` |
+
+## 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,75 @@
+{
+  "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    },
+    {
+      "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": []
+    }
+  ]
+}

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]