@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/skills/creating-skills/references/progressive-disclosure.md

@@ -0,0 +1,176 @@
+# Progressive Disclosure
+
+The canonical load-level model for Plastic skills, agents, and hooks. Every other
+reference and the SKILL.md body point here for this model and must not restate it (C7).
+Read it before authoring any skill body, before splitting content into `references/`,
+and before deciding where a file goes (scripts, references, or assets).
+
+## Contents
+
+- [The three load levels](#the-three-load-levels)
+- [When to split the body into references](#when-to-split-the-body-into-references)
+- [Bucket selection: scripts vs references vs assets](#bucket-selection-scripts-vs-references-vs-assets)
+- [Reference-link discipline (C4)](#reference-link-discipline-c4)
+- [One level deep, with a table of contents (C5, C6)](#one-level-deep-with-a-table-of-contents-c5-c6)
+- [Store each fact once (C7)](#store-each-fact-once-c7)
+- [Cross-reference other skills by name (C8)](#cross-reference-other-skills-by-name-c8)
+- [Ship only what does the job (C9)](#ship-only-what-does-the-job-c9)
+- [The thin-router pattern (C10)](#the-thin-router-pattern-c10)
+- [Quarantine worked examples (C11)](#quarantine-worked-examples-c11)
+
+## The three load levels
+
+Treat each level as a hard design target, not a guideline. The agent platform loads
+each level at a different moment, so a fact in the wrong level either burns context that
+is always present or never arrives when needed. [C1]
+
+| Level | What lives here | Budget | When it loads |
+|-------|-----------------|--------|---------------|
+| Metadata | `name` + `description` frontmatter | ~100 tokens | Always, for every skill in the catalog |
+| Body | `SKILL.md` after the frontmatter | under 5000 tokens / under 500 lines | On trigger (description matches the request) |
+| Resources | files in `references/`, `scripts/`, `assets/` | unbounded | On demand (the body points to them, or the agent runs them) |
+
+Consequences that drive every other rule in this file:
+
+1. Metadata is paid for on every request, so the description earns its ~100 tokens by
+   triggering correctly and nothing more. Authoring rules for the description live in
+   `skills.md`.
+2. Body tokens are paid for only when the skill fires, but then they are paid in full.
+   Keep the body to the non-skippable rules plus routing. Push how-to down to resources.
+3. Resource tokens are paid for only when the agent reaches the file. This is where
+   depth, variants, and worked examples belong.
+
+## When to split the body into references
+
+Split when the body approaches the budget or carries material the agent does not need on
+every run. Move out first, in this order: advanced cases, variant paths, long worked
+examples, deep domain background. Keep inline only the core workflow plus the selection
+guidance that tells the agent which path or reference to take. [C2]
+
+Move to `references/`:
+
+- Detailed procedures the agent needs only for one task shape.
+- Advanced or edge-case handling most runs never hit.
+- Variant flows (one file per variant) so the common path stays short.
+- Long examples and tables that document rather than instruct.
+
+Keep in the body:
+
+- The non-skippable rules (the ones an agent must not get wrong even if it never opens a
+  reference).
+- The routing table that maps a request shape to the right reference.
+- Selection guidance: how to choose between the references and paths on offer.
+
+## Bucket selection: scripts vs references vs assets
+
+Choose the bucket by how the file touches the context window, not by file type. [C3]
+
+| Bucket | Relationship to context | Use for |
+|--------|-------------------------|---------|
+| `scripts/` | Executed, not read. Output enters context, the source does not. | Deterministic logic the agent would otherwise re-derive each run: validators, generators, formatters. See `scripts.md`. |
+| `references/` | Read only when the body points the agent to it. | Depth, procedures, variants, examples that instruct. |
+| `assets/` | Copied into output, never read into context. | Templates, boilerplate, fixtures the agent emits or copies verbatim. |
+
+Decision rule: if the content is logic that runs, put it in `scripts/` and document the
+interface (`--help`, exit codes) rather than the implementation. If it is knowledge the
+agent reads to decide or act, put it in `references/`. If it is bytes the agent copies
+into its output without reading, put it in `assets/`.
+
+## Reference-link discipline (C4)
+
+Bind every reference link to an observable trigger: a condition the agent can check
+against the request or the run state. Never ship a bare "see references/ for more". A
+bare pointer makes loading a judgment call, so the agent either loads everything (burning
+the budget the split was meant to save) or loads nothing (and acts blind). [C4]
+
+| Form | Verdict |
+|------|---------|
+| `Read references/hooks.md when authoring a lifecycle hook.` | Good. Trigger is the task shape. |
+| `Read references/errors.md when the API returns a non-200 status.` | Good. Trigger is observable run state. |
+| `See references/ for more detail.` | Bad. No trigger; loading is a guess. |
+| `Refer to the references as needed.` | Bad. "As needed" is not a condition. |
+
+Write the trigger as the request shape the agent can match ("when authoring an agent",
+"when the user names a hook event") or a run-state signal it can read ("when the test
+suite reports a failure", "when the frontmatter validator exits non-zero").
+
+## One level deep, with a table of contents (C5, C6)
+
+Keep every reference exactly one level deep from `SKILL.md`: the body links to
+`references/x.md`, and `references/x.md` does not link onward to a further file the agent
+must chase. Nested references get head-previewed by the platform, so the agent acts on a
+partial read and misses content below the preview window. Flatten instead: if a reference
+grows a second level, split it into sibling files the body routes to directly. [C5]
+
+Add a table of contents to the top of any reference over 100 lines so the agent can jump
+to the relevant section instead of reading linearly. For very large files, put grep
+patterns in the body so the agent can locate a section without loading the whole file.
+[C6]
+
+## Store each fact once (C7)
+
+Keep each fact in exactly one place. Do not restate a rule across the body and a
+reference, across two references, or across two skills. Duplicated doctrine drifts: one
+copy gets updated, the other goes stale, and the agent cannot tell which is current. When
+two files need the same fact, one owns it and the other points to the owner.
+
+This file owns the load-level model. The body and the other references point here for it
+and do not repeat the table or the budgets. [C7]
+
+## Cross-reference other skills by name (C8)
+
+Name a required companion skill with a requirement marker, not a path. Use a line the
+agent reads as a dependency it loads on its own terms. [C8]
+
+| Form | Effect |
+|------|--------|
+| `REQUIRED BACKGROUND: superpowers:test-driven-development` | Good. Names the dependency; the agent loads it when relevant. |
+| `For eval depth, use plastic-evaluating-skills.` | Good. Names the skill, leaves loading to the agent. |
+| `@skills/evaluating-skills/SKILL.md` | Bad. `@`-path syntax force-loads the file immediately, defeating disclosure. |
+
+The `@`-path form pulls the target into context the moment the line is read, so it spends
+the budget the level split was built to protect. Name the skill and let the trigger
+decide when it loads.
+
+## Ship only what does the job (C9)
+
+Ship the SKILL.md, the references the body routes to, the scripts it runs, and the assets
+it copies. Nothing else. No README, CHANGELOG, or QUICK_REFERENCE inside a skill: the
+description is the skill's front door, and a second front door duplicates it (C7) and adds
+files the agent must skip past. No orphan files (a file no link points to and no script
+runs). If nothing reaches a file, delete it. [C9]
+
+## The thin-router pattern (C10)
+
+For a knowledge-heavy domain (one with many distinct request shapes, each needing
+different depth), make the body a thin router: a short header of non-skippable rules plus
+a table that maps a request shape to the one reference that handles it. The body inlines
+no how-to. It decides which reference to load and stops. [C10]
+
+Router body shape:
+
+```
+# skill-name
+
+<non-skippable rules: the few facts an agent must not get wrong>
+
+## Routing
+
+| When the task is... | Read |
+|---------------------|------|
+| authoring an Agent Skill | references/skills.md |
+| authoring a subagent     | references/agents.md |
+| authoring a lifecycle hook | references/hooks.md |
+```
+
+The router keeps the always-paid body cost flat as the domain grows: adding a new request
+shape adds one reference and one table row, not more body. Each reference stays focused on
+its one shape.
+
+## Quarantine worked examples (C11)
+
+Keep the maxim in context, keep the example out of it. State the rule in the body or the
+reference; move long worked examples to a file the agent loads only when it needs to see
+the rule applied. An example is illustration, not instruction: it is paid for on every run
+if it sits in the body, but it is needed only when the rule alone is not enough. Put the
+short rule where it triggers, and route to the example with a trigger condition (C4). [C11]

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

@@ -0,0 +1,166 @@
+# Scripts: when deterministic code beats prose
+
+Decide whether a skill ships a script, and write scripts that hold their determinism.
+Read this when choosing script versus prose, or when writing a script that ships with a
+skill.
+
+For which bucket holds a given piece of content (scripts versus references versus
+assets), read `references/progressive-disclosure.md`. This file covers only the
+script-or-prose decision and script discipline.
+
+## Contents
+
+- [Ship a script or write prose](#ship-a-script-or-write-prose)
+- [The three-way test](#the-three-way-test)
+- [Make scripts solve, not punt](#make-scripts-solve-not-punt)
+- [Test by running](#test-by-running)
+- [Match freedom to fragility](#match-freedom-to-fragility)
+- [Wire validators into hooks](#wire-validators-into-hooks)
+- [Script hard requirements](#script-hard-requirements)
+- [Plastic conventions](#plastic-conventions)
+- [Worked example](#worked-example)
+- [Self-check](#self-check)
+
+## Ship a script or write prose
+
+Ship a script when either condition holds:
+
+1. The same code gets rewritten on every run.
+2. Deterministic reliability matters (one wrong character breaks the result).
+
+Otherwise write prose. A script is executed, not loaded, so its body stays out of
+context and costs no tokens at trigger time. The price is an indirection: the agent must
+find the script, learn its interface, and run it. Pay that price only when repetition or
+determinism earns it. [G1]
+
+## The three-way test
+
+When something repeats, route it by what repeats, not by gut feel. [G2]
+
+| What repeats | Bucket | Why |
+| --- | --- | --- |
+| Identical code | `scripts/` | Run it; do not regenerate it each time. |
+| Identical boilerplate output | `assets/` (template) | Copy the template into output; never read it into context. |
+| Re-discovered facts | `references/` | Read it once, on the trigger that needs it. |
+
+A symptom of the wrong choice: an agent pasting the same 30 lines of Ruby across three
+runs belongs in `scripts/`, not in prose; a fixed file header the agent retypes belongs
+in `assets/`; a constant the agent keeps looking up belongs in `references/`.
+
+## Make scripts solve, not punt
+
+A script that hands its failure back to the agent loses the determinism that justified
+shipping it. [G3]
+
+- Handle errors inside the script. Catch the failure, print a clear diagnostic to stderr,
+  and exit non-zero. Do not raise a raw stack trace and leave the agent to interpret it.
+- No voodoo constants. Every magic number, path, or threshold gets a name and a comment
+  stating where it came from. An unexplained `0.87` is a future break.
+- State the mode. Say explicitly whether the agent executes the script or reads it. A
+  validator is executed; a snippet meant to be copied is read. Ambiguity makes the agent
+  guess.
+
+## Test by running
+
+An untested script is a latent break. Run it against real input before shipping. [G4]
+
+- Exercise the success path and at least one failure path; confirm the exit code and the
+  stderr message.
+- Delete any example or scratch files the run generated that the skill does not ship.
+  Stray files are clutter and may load by accident.
+
+## Match freedom to fragility
+
+Match degrees of freedom to fragility. Put guardrails on the narrow bridge, not the open
+field. [G6]
+
+| Task shape | Form | Reason |
+| --- | --- | --- |
+| Open, judgment-heavy | Prose | The agent needs room to adapt; code would over-constrain. |
+| A preferred, repeatable pattern | Parameterized script (flags/env) | One correct shape, with controlled variation. |
+| Fragile or destructive sequence | Fixed "do not modify" script | One exact path; any edit risks data loss. |
+
+Mark a fragile script as "do not modify" in its `--help` and in the pointer that sends the
+agent to it. For side-effecting workflows, gate execution behind a validator (see below)
+rather than trusting the agent to check preconditions by hand.
+
+## Wire validators into hooks
+
+When a rule must hold every time, wire a deterministic validator into a hook rather than
+restating the rule in prose. [G5]
+
+- A `PreToolUse` validator can refuse an action before it runs; a packaging step can
+  refuse to ship a skill that fails validation.
+- Gate destructive steps behind validate-then-act: the validator passes, then the action
+  runs. A prose reminder ("remember to check X first") is probabilistic; a hook is not.
+
+For hook event selection, exit-code semantics, and path conventions, read
+`references/hooks.md`.
+
+## Script hard requirements
+
+Every script that ships with a skill meets these, because an agent runs it unattended:
+
+1. No interactive prompts. A blocking `gets` or `read -p` hangs the agent forever. Take
+   all input up front.
+2. Input via flags, environment variables, or stdin. Never mid-run questions.
+3. `--help` is the primary documentation. Describe purpose, every flag, input, output, and
+   exit codes there, so the agent learns the interface without reading the source.
+4. Structured output. Data on stdout, diagnostics and progress on stderr, so the caller
+   can capture one without the other.
+5. Idempotent operations. Running twice produces the same end state; re-running after a
+   partial failure is safe.
+6. Meaningful, documented exit codes. 0 for success, distinct non-zero codes for distinct
+   failures, each named in `--help`.
+
+## Plastic conventions
+
+- Scripts ship in Ruby. A worked example that shows a script shows Ruby.
+- Any shell script runs under macOS `/bin/bash` 3.2. No `bash` 4.x features (no
+  associative arrays, no `mapfile`, no `${var^^}`), and no heredocs inside `$(...)`.
+
+## Worked example
+
+A skill validates that an intent slug is well formed before any directory is created. The
+check runs on every intent and must be exact, so it ships as a script, not prose. [G1][G3]
+
+`scripts/validate_slug.rb`:
+
+```ruby
+#!/usr/bin/env ruby
+# Validate an intent slug. Execute this; do not inline its logic.
+# Usage: validate_slug.rb SLUG
+# Exit: 0 valid, 1 malformed, 2 wrong argument count.
+
+# Convention source: A5 of the best-practices standard (lowercase,
+# digits, single hyphens, no leading/trailing/consecutive hyphens).
+SLUG_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+
+if ARGV.length != 1
+  warn "usage: validate_slug.rb SLUG"
+  exit 2
+end
+
+slug = ARGV.fetch(0)
+if SLUG_PATTERN.match?(slug)
+  puts slug            # data on stdout
+  exit 0
+else
+  warn "malformed slug: #{slug.inspect}" # diagnostic on stderr
+  exit 1
+end
+```
+
+This script earns its place: identical code on every run, one exact rule, errors handled
+inside, the named constant cites its source, data on stdout and diagnostics on stderr,
+documented exit codes, and the header states it is executed. An open task ("name this
+intent well") would stay prose; this fixed check is a script.
+
+## Self-check
+
+- Does this code repeat or demand exactness? If not, it stays prose. [G1]
+- Did the right bucket win the three-way test? [G2]
+- Are errors handled inside, constants named, and the execute-or-read mode stated? [G3]
+- Did the script run green on a success path and a failure path, with scratch files
+  removed? [G4]
+- Does fragility match form, with destructive steps gated by a validator? [G5][G6]

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

@@ -0,0 +1,165 @@
+# Authoring an Agent Skill
+
+Open this when writing or restructuring a single Agent Skill: the frontmatter, the
+description that triggers it, the body voice, and the on-disk layout. Rule ids in brackets
+(A1 through B10) point at the synthesis standard the rules come from.
+
+For the three load levels (metadata, body, resources), the thin-router pattern, and how to
+split a body into `references/`, read `progressive-disclosure.md`. This file does not repeat
+that model.
+
+## Contents
+
+- Skill file layout
+- Frontmatter fields
+- The `name` field
+- The `description` field (triggering)
+- Optional frontmatter fields
+- Body voice
+- Body content
+- Self-check
+
+## Skill file layout
+
+A skill is a directory whose name matches the `name` field. The directory holds `SKILL.md`
+plus optional buckets. Pick a bucket by how the file touches context.
+
+| Path | Loads when | Holds |
+|------|-----------|-------|
+| `SKILL.md` | The skill triggers | Frontmatter plus the body |
+| `references/` | The body points at it, on demand | Deep how-to, specs, variant material |
+| `scripts/` | Executed, never read into context | Repeated deterministic code |
+| `assets/` | Copied into output, never read | Templates, boilerplate the output needs |
+| `evals/` | Run by the eval harness | Eval cases for the skill |
+
+When picking a bucket, follow `progressive-disclosure.md` for the cross-cutting layout rules:
+references one level deep (C5), no orphan or auxiliary files in the skill (C9), and each fact
+stored once (C7).
+
+## Frontmatter fields
+
+`SKILL.md` opens with YAML frontmatter. Two fields are required.
+
+| Field | Required | Constraints |
+|-------|----------|-------------|
+| `name` | Yes | 1 to 64 chars. Lowercase alphanumeric plus hyphens. No leading, trailing, or consecutive hyphens. Matches the directory name. |
+| `description` | Yes | 1 to 1024 chars. Non-empty. States what and when. |
+
+Invent no other top-level fields. Unknown fields are ignored or rejected and add noise [A6].
+
+## The `name` field
+
+Rules [A5]:
+
+1. 64 chars or fewer.
+2. Lowercase letters, numbers, and hyphens only.
+3. No leading, trailing, or consecutive hyphens.
+4. Must match the parent directory name exactly.
+5. Must not contain `anthropic` or `claude`.
+6. Prefer the gerund form, which reads as a capability (`processing-pdfs`, `creating-skills`,
+   not `pdf-tool`).
+
+## The `description` field (triggering)
+
+The description is the only text loaded at discovery time. The body is not loaded when the
+agent decides whether to trigger, so the description alone has to win the match.
+
+Rules:
+
+1. Write the description as triggering conditions only ("Use when ..."), never as a summary of
+   the workflow [A1]. A workflow summary makes the agent act on the summary and skip the body,
+   dropping steps. Documented failure: a description that summarized "code review between
+   tasks" produced one review instead of two.
+2. Write in the third person [A2]. The description is injected into the system prompt, where
+   mixed point of view degrades discovery.
+3. State both what the skill does and when to use it, and front-load concrete trigger terms
+   [A3]. The model picks from many skills on this text and the listing is budget-truncated, so
+   terms placed late may never be read.
+4. Include at least one indirect trigger where the user does not name the domain [A4]. Real
+   prompts rarely name the skill, so a keyword-only description misses oblique requests.
+
+Shape:
+
+```yaml
+description: >
+  [One clause: what it does]. Use when [primary trigger], [secondary trigger],
+  or when [indirect trigger where the user does not name the domain].
+```
+
+For side-effecting workflows (deploy, release, destructive ops), set
+`disable-model-invocation: true` so only the user fires the skill [A7]. Auto-triggering on
+irreversible work is a known failure mode.
+
+## Optional frontmatter fields
+
+Use only the documented optionals below. Add nothing beyond them [A6].
+
+| Field | Holds |
+|-------|-------|
+| `license` | Short name or filename reference |
+| `compatibility` | Environment requirements, 1 to 500 chars, only when needed |
+| `metadata` | String-to-string map with unique keys |
+| `allowed-tools` | Space-separated tool list (experimental) |
+| `model` | Claude Code extension: pin the model for this skill |
+| `disable-model-invocation` | Claude Code extension: only the user may fire the skill |
+| `context: fork` | Claude Code extension: run the body as a forked task |
+| `paths` | Claude Code extension: scope the skill to matching paths |
+
+## Body voice
+
+Rules:
+
+1. Write in imperative or infinitive voice ("Run the validator", "Extract the text"), never
+   second person ("you should", "you can") [B1]. Command voice is shorter and binds tighter;
+   hedged second-person language is a known slop pattern.
+2. Use one consistent term per concept ("extract", never also "pull", "get", "retrieve")
+   [B6]. Synonym drift makes the agent unsure whether two terms name the same operation.
+
+## Body content
+
+The body persists in context every turn the skill is active, so each line is a recurring
+cost. Spend lines only where the agent would otherwise go wrong.
+
+Rules:
+
+1. State what to do, not how or why, and cut anything the model already knows [B2]. Claude is
+   already capable; the body is for the project-specific and the non-obvious.
+2. Apply the test "would the agent get this wrong without it?" to every instruction. If no,
+   delete it [B7]. Instructions that restate default competence are pure token cost.
+3. Challenge every paragraph with "does this justify its token cost?" and prefer one excellent
+   example over many mediocre ones [B3].
+4. Lead each section with one bold maxim and close it with one concrete self-check [B4]. The
+   maxim is what survives in context; the check lets the agent apply the rule mid-task.
+5. Put gotchas as concrete corrections, placed early [B5]. A correction only helps if the
+   agent reads it before it makes the mistake. Write the specific fact, not general advice:
+
+   ```markdown
+   ## Gotchas
+   - The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL`.
+   - User id is `user_id` in the DB, `uid` in auth, `accountId` in billing. Same value.
+   - The `/health` endpoint returns 200 even when the DB is down. Use `/ready`.
+   ```
+
+6. Carry reference and decision material in tables and numbered lists. Use a flowchart only
+   for a genuinely non-obvious decision or an early-stop loop [B10]. Tables are denser per
+   token; flowcharts waste tokens on reference, code, or linear steps.
+7. State the tradeoff and ship an escape hatch instead of policing edge cases with long
+   rationalization tables [B8]. Add an Excuse-and-Reality table only for a discipline skill
+   where an eval has actually shown the agent rationalizing a violation.
+8. Avoid time-sensitive content. Move deprecated material into a collapsed "Old patterns"
+   section [B9]. Dated instructions rot and mislead.
+
+## Self-check
+
+Before shipping the skill, confirm each line:
+
+- [ ] `name` matches the directory, is lowercase-hyphen, and carries no `claude`/`anthropic`.
+- [ ] `description` reads as "Use when ...", third person, with front-loaded triggers and at
+      least one indirect trigger.
+- [ ] No invented frontmatter fields; optionals are drawn only from the table above.
+- [ ] Side-effecting skill sets `disable-model-invocation`.
+- [ ] Body is imperative, with one term per concept.
+- [ ] Every instruction passes "would the agent get this wrong without it?".
+- [ ] Gotchas are concrete corrections, placed early.
+- [ ] Reference and decision material is in tables or lists, not prose.
+- [ ] `references/` files are one level deep; no orphan or auxiliary files in the skill.