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

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.

package/skills/creating-skills/scripts/scaffold.rb

@@ -0,0 +1,313 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# scaffold.rb - born-slim starting files for a new skill, agent, or hook.
+#
+# Plastic skills, agents, and hooks start small and grow by progressive
+# disclosure. This scaffolder emits the minimum valid skeleton so the body
+# stays slim and detail moves into references/ as the work earns it.
+#
+# Usage:
+#   ruby scaffold.rb skill <name> [--out <dir>] [dest]
+#   ruby scaffold.rb agent <name> [--out <dir>] [dest]
+#   ruby scaffold.rb hook  [<Event>] <name> [--out <dir>] [dest]
+#   ruby scaffold.rb --help
+#
+# All input is positional plus flags. There are no interactive prompts, so an
+# agent never hangs waiting on input. The destination defaults to the current
+# directory; pass --out or a trailing positional to choose another directory.
+#
+# Exit codes:
+#   0  success, or --help
+#   1  usage error (unknown subcommand, missing argument)
+#   2  validation error (bad name or event)
+#   3  refused to overwrite an existing target, or a filesystem error
+#
+# This script and every file it emits contain no em-dashes; the emitted files
+# are user-facing.
+
+require "json"
+require "fileutils"
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_VALIDATION = 2
+EXIT_CONFLICT = 3
+
+NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/.freeze
+EVENT_PATTERN = /\A[A-Z][A-Za-z]+\z/.freeze
+DEFAULT_EVENT = "PostToolUse"
+
+USAGE = <<~TEXT
+  scaffold.rb - born-slim starting files for a new skill, agent, or hook.
+
+  Usage:
+    ruby scaffold.rb skill <name> [--out <dir>] [dest]
+    ruby scaffold.rb agent <name> [--out <dir>] [dest]
+    ruby scaffold.rb hook  [<Event>] <name> [--out <dir>] [dest]
+    ruby scaffold.rb --help
+
+  Subcommands:
+    skill   Emit <dest>/<name>/SKILL.md, references/.gitkeep, evals/evals.json.
+    agent   Emit <dest>/<name>.md agent role file.
+    hook    Emit <dest>/<name> no-op hook handler (Ruby) wired for <Event>.
+
+  Names must be lowercase alphanumeric and hyphens, with no leading,
+  trailing, or repeated hyphens, 1 to 64 characters.
+  The hook <Event> is optional and defaults to #{DEFAULT_EVENT}.
+  The destination defaults to the current directory.
+
+  Exit codes:
+    0  success, or --help
+    1  usage error (unknown subcommand, missing argument)
+    2  validation error (bad name or event)
+    3  refused to overwrite an existing target, or a filesystem error
+TEXT
+
+# A small error that carries the exit code to use when it reaches the top.
+class ScaffoldError < StandardError
+  attr_reader :code
+
+  def initialize(message, code)
+    super(message)
+    @code = code
+  end
+end
+
+def fail_with(message, code)
+  raise ScaffoldError.new(message, code)
+end
+
+def validate_name!(name)
+  if name.nil? || name.empty?
+    fail_with("missing <name>. See --help for usage.", EXIT_USAGE)
+  end
+  unless name.length <= 64 && name =~ NAME_PATTERN
+    fail_with(
+      "invalid name #{name.inspect}: use lowercase letters, digits, and " \
+      "hyphens, no leading, trailing, or repeated hyphens, 1 to 64 chars.",
+      EXIT_VALIDATION
+    )
+  end
+  name
+end
+
+def validate_event!(event)
+  unless event =~ EVENT_PATTERN
+    fail_with(
+      "invalid event #{event.inspect}: use a CamelCase hook event name, " \
+      "for example PostToolUse or SessionStart.",
+      EXIT_VALIDATION
+    )
+  end
+  event
+end
+
+# Separate --out and any trailing positional dest from the bare positionals.
+# Returns [positionals, out_dir]. out_dir is nil when not given.
+def parse_args(args)
+  positionals = []
+  out_dir = nil
+  i = 0
+  while i < args.length
+    arg = args[i]
+    case arg
+    when "--out"
+      out_dir = args[i + 1]
+      if out_dir.nil?
+        fail_with("--out needs a directory argument.", EXIT_USAGE)
+      end
+      i += 2
+    else
+      if arg.start_with?("--")
+        fail_with("unknown option #{arg.inspect}. See --help for usage.", EXIT_USAGE)
+      end
+      positionals << arg
+      i += 1
+    end
+  end
+  [positionals, out_dir]
+end
+
+def refuse_if_exists!(path)
+  if File.exist?(path)
+    fail_with("refusing to overwrite existing #{path}. Remove it or pick another destination.", EXIT_CONFLICT)
+  end
+end
+
+def write_file(path, content)
+  refuse_if_exists!(path)
+  FileUtils.mkdir_p(File.dirname(path))
+  File.write(path, content)
+  puts "created #{path}"
+end
+
+# -- generators ----------------------------------------------------------
+
+def skill_body(name)
+  <<~MD
+    ---
+    name: #{name}
+    description: >
+      Use when the user needs #{name}. State here WHEN this skill should
+      trigger, in the third person, so the agent can match it. Replace this
+      placeholder with one or two concrete trigger conditions before shipping.
+    ---
+
+    # #{name}
+
+    One line on what this skill does and why it exists.
+
+    ## Gotchas
+
+    - List the non-obvious failure modes here, one per line.
+
+    ## Tasks
+
+    Keep the body slim. Route detail to references as the work earns it.
+
+    | Task | Reference |
+    | ---- | --------- |
+    | Replace this row with a real task | references/REPLACE-ME.md |
+  MD
+end
+
+def eval_stub(name)
+  data = {
+    "skill_name" => name,
+    "evals" => [
+      {
+        "id" => 1,
+        "prompt" => "",
+        "expected_output" => "",
+        "files" => [],
+        "assertions" => []
+      }
+    ]
+  }
+  JSON.pretty_generate(data) + "\n"
+end
+
+def generate_skill(name, out_dir)
+  base = File.join(out_dir, name)
+  refuse_if_exists!(base)
+  write_file(File.join(base, "SKILL.md"), skill_body(name))
+  write_file(File.join(base, "references", ".gitkeep"), "")
+  write_file(File.join(base, "evals", "evals.json"), eval_stub(name))
+  puts "skill scaffold ready at #{base}"
+end
+
+def agent_body(name)
+  <<~MD
+    ---
+    name: #{name}
+    description: >
+      Use this agent when the user needs #{name}. State here WHEN to delegate
+      to this agent, in the third person, so the orchestrator can route to it.
+      Replace this placeholder with concrete delegation conditions.
+    tools: Read, Edit, Bash
+    ---
+
+    You are the #{name} agent.
+
+    ## Responsibilities
+
+    - One line per durable responsibility this agent owns.
+
+    ## How you work
+
+    Keep this body slim. State the contract, the inputs, and the outputs.
+    Move long procedures into a references file as the work earns it.
+
+    ## Completion
+
+    End your turn with a short report of what you did and how you verified it.
+  MD
+end
+
+def generate_agent(name, out_dir)
+  write_file(File.join(out_dir, "#{name}.md"), agent_body(name))
+  puts "agent scaffold ready at #{File.join(out_dir, "#{name}.md")}"
+end
+
+def hook_body(name, event)
+  <<~RUBY
+    #!/usr/bin/env ruby
+    # frozen_string_literal: true
+
+    # #{name} - #{event} hook handler (no-op by default).
+    #
+    # This skeleton does nothing until you opt in. Set the environment flag
+    # below to a non-empty value to activate the real behavior. Until then it
+    # exits 0 so it never blocks the session.
+    #
+    # Wire it in settings.json under hooks.#{event}:
+    #   { "type": "command", "command": "ruby /absolute/path/to/#{name}" }
+    #
+    # Exit codes:
+    #   0  no-op, or success
+    #   2  block the action (only when you add real logic that should block)
+
+    OPT_IN = "#{name.tr("-", "_").upcase}_ENABLED"
+
+    if ENV[OPT_IN].nil? || ENV[OPT_IN].empty?
+      exit 0
+    end
+
+    # Opt-in is set. Add the real handler here. The hook receives event JSON on
+    # stdin; parse it only when you need it. Exit 0 to allow, exit 2 to block.
+    exit 0
+  RUBY
+end
+
+def generate_hook(name, event, out_dir)
+  path = File.join(out_dir, name)
+  write_file(path, hook_body(name, event))
+  FileUtils.chmod("+x", path)
+  puts "hook scaffold ready at #{path} (executable, #{event}, no-op until opt-in)"
+end
+
+# -- dispatch ------------------------------------------------------------
+
+def run(argv)
+  if argv.empty? || argv.include?("--help") || argv.include?("-h")
+    puts USAGE
+    return EXIT_OK
+  end
+
+  subcommand = argv.shift
+  positionals, out_flag = parse_args(argv)
+
+  case subcommand
+  when "skill", "agent"
+    name = validate_name!(positionals[0])
+    out_dir = out_flag || positionals[1] || "."
+    subcommand == "skill" ? generate_skill(name, out_dir) : generate_agent(name, out_dir)
+  when "hook"
+    # Accept "hook <name>" or "hook <Event> <name>", with an optional trailing dest.
+    if positionals.length >= 2 && positionals[0] =~ EVENT_PATTERN
+      event = validate_event!(positionals[0])
+      name = validate_name!(positionals[1])
+      out_dir = out_flag || positionals[2] || "."
+    else
+      event = DEFAULT_EVENT
+      name = validate_name!(positionals[0])
+      out_dir = out_flag || positionals[1] || "."
+    end
+    generate_hook(name, event, out_dir)
+  else
+    fail_with("unknown subcommand #{subcommand.inspect}. See --help for usage.", EXIT_USAGE)
+  end
+
+  EXIT_OK
+end
+
+begin
+  exit run(ARGV.dup)
+rescue ScaffoldError => e
+  warn "scaffold.rb: #{e.message}"
+  exit e.code
+rescue Errno::EACCES, Errno::ENOENT, Errno::EEXIST => e
+  warn "scaffold.rb: filesystem error: #{e.message}"
+  exit EXIT_CONFLICT
+end

package/skills/writing-instructions/SKILL.md

@@ -1,159 +0,0 @@
----
-name: plastic-writing-instructions
-description: >
-  Write or restructure agent instructions, conventions files, and SKILL.md
-  content using progressive disclosure and the agentskills.io specification.
-  Use when creating PLASTIC.md, rewriting convention docs, authoring new
-  skills, restructuring large instruction files to fit context budgets,
-  or when instructions feel too long, too vague, or agents aren't following
-  them. Also use when the user says "progressive disclosure", "restructure
-  instructions", or "the instructions are too big".
----
-
-# Writing Agent Instructions
-
-Based on the [agentskills.io specification](https://agentskills.io).
-
-## Progressive Disclosure Architecture
-
-All agent instructions follow three loading stages. Design for this — it's the
-architecture, not a nice-to-have.
-
-| Stage | What loads | Budget | Design for |
-|-------|-----------|--------|------------|
-| **Discovery** | name + description | ~100 tokens | Trigger accuracy |
-| **Activation** | Full instruction body | <5000 tokens / <500 lines | Core procedures |
-| **Execution** | references/, scripts/, assets/ | As needed | Deep detail |
-
-**The description carries the entire burden of triggering.** If agents aren't
-activating your skill, the description is the problem.
-
-## Procedure
-
-### Step 1: Audit the content
-
-Before writing or restructuring, classify every piece of content:
-
-| Classification | Where it goes | Example |
-|---------------|---------------|---------|
-| **Trigger context** | description field | "Use when...", keywords |
-| **Core procedure** | SKILL.md body | Step-by-step workflows |
-| **Gotchas** | SKILL.md body (early) | Facts that defy assumptions |
-| **Deep reference** | references/ | API details, full schemas |
-| **Templates** | assets/ or inline | Output format examples |
-| **Executable logic** | scripts/ | Validation, data processing |
-
-Ask for each piece: "Would the agent get this wrong without this?"
-If no — cut it. If unsure — test it.
-
-### Step 2: Write the description
-
-The description must convey WHEN to use, not just WHAT it does.
-
-**Rules:**
-- Imperative phrasing: "Use this skill when..." not "This skill does..."
-- Focus on user intent, not implementation
-- Err on the side of being pushy — list contexts explicitly
-- Include cases where user doesn't name the domain directly
-- Under 1024 characters (hard limit)
-- Include specific trigger keywords
-
-**Template:**
-```yaml
-description: >
-  [One sentence: what it does]. Use when [primary trigger context],
-  [secondary trigger], or when [indirect trigger where user doesn't
-  name the domain]. Also use when [edge case trigger].
-```
-
-### Step 3: Write the body
-
-**Principles (in priority order):**
-
-1. **Procedures over declarations** — Teach HOW to approach a class of problems,
-   not WHAT to produce for a specific instance
-2. **Defaults, not menus** — Pick one approach, mention alternatives briefly.
-   "Use X. For Y cases, use Z instead." Never present options as equals.
-3. **Calibrate control to fragility** — Prescriptive for fragile/sequential tasks,
-   flexible when multiple approaches are valid. Most skills have a mix.
-4. **Reasoning over rigid directives** — "Do X because Y tends to cause Z" beats
-   "ALWAYS do X, NEVER do Y"
-5. **Add what the agent lacks, omit what it knows** — No explaining HTTP, PDFs,
-   or what a migration is. Jump to what's non-obvious.
-
-**Structure:**
-```markdown
-# Title
-
-[1-2 sentence purpose statement]
-
-## Gotchas
-- [Highest-value content first — facts that defy assumptions]
-- [Each gotcha is a concrete correction, not general advice]
-
-## Procedure
-### Step 1: ...
-### Step 2: ...
-
-## Patterns
-[Only if the skill covers multiple approaches to similar problems]
-```
-
-### Step 4: Extract to references/
-
-Anything over 500 lines or 5000 tokens goes to `references/`. But tell the
-agent WHEN to load each file — conditional references, not a generic "see
-references/ for details."
-
-**Good:** "Read `references/api-errors.md` if the API returns a non-200 status"
-**Bad:** "See references/ for more information"
-
-### Step 5: Validate
-
-Run through this checklist:
-
-- [ ] Description under 1024 chars
-- [ ] Body under 500 lines / 5000 tokens
-- [ ] Every instruction passes "would the agent get this wrong without it?"
-- [ ] Gotchas are concrete corrections, not general advice
-- [ ] Defaults chosen, not menus presented
-- [ ] Control calibrated: prescriptive where fragile, flexible where tolerant
-- [ ] References have conditional load triggers
-- [ ] No explaining what the agent already knows
-
-For structured evaluation beyond this checklist (paired evals, pass rate
-tracking, regression testing), use `plastic-evaluating-skills`.
-
-## Gotchas
-
-- Hook `additionalContext` truncates at **10,000 characters**. If instructions
-  must load via hooks (not skills), they must fit this budget.
-- `~/.claude/rules/*.md` files load fully with no truncation — use for
-  always-loaded conventions that don't fit in a skill.
-- CLAUDE.md supports `@path/to/file` imports (max depth 4) — another way
-  to load large instruction sets without truncation.
-- Agents only consult skills for tasks beyond what they can handle alone.
-  Simple one-step requests may not trigger even with a perfect description.
-- Content from real domain expertise (runbooks, incident reports, code review)
-  dramatically outperforms LLM-generated instructions without project context.
-- The most common cause of agents not following instructions: the instruction
-  was too vague, didn't apply to the current task, or presented too many
-  options without a clear default. Read execution traces to diagnose.
-
-## For Convention Files (PLASTIC.md, CLAUDE.md)
-
-Convention files aren't skills — they load differently. Apply progressive
-disclosure by splitting:
-
-| Layer | Mechanism | Budget | Content |
-|-------|-----------|--------|---------|
-| **Always-on** | `~/.claude/rules/` or hook | <10K chars | Core identity, gotchas, critical procedures |
-| **On-demand** | Skills (SKILL.md) | <5K tokens each | Specific workflows activated by task |
-| **Deep reference** | `references/` in skills | Unlimited | Full specs, schemas, examples |
-
-**The always-on layer should answer: "What does this agent need to know about
-every single task?"** Everything else activates on demand.
-
-## References
-
-- Read `references/agentskills-spec.md` for the complete agentskills.io specification including frontmatter fields, description optimization methodology, evaluation framework, and script design requirements