@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

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/dashboard/SKILL.md

@@ -67,6 +67,11 @@ instead of showing it.
 
 ### Step 4 — Entry flow (the board is the menu)
 
+QMD-first (when available): when the user navigates by describing an intent rather than giving its
+id, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"`
+to surface the candidate intent, then open the authoritative intent file for the hit. The command is
+a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
+
 The board lists everything; the user navigates by free prose (no capped picker):
 - On the **global** board, the user replies with an **intent id** (work it), a **project
   name** (re-run `project <slug> --data` and present that board), or **"new"** (start a new

package/skills/dashboard/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-dashboard",
+  "notes": "Intent 66a. Spec for the QMD-first step in the entry flow (resolve a free-prose intent reference before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. On the board, the user navigates by describing an intent (the search verb work) instead of giving its id.",
+      "expected_output": "Before scanning the store with grep/Read to resolve the free-prose reference, runs `ruby ~/.plastic/scripts/qmd-sync search \"search verb\"` to surface the candidate intent, then opens the authoritative intent file for the hit. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read when the user navigates by description; authoritative file opened for the hit",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/executing-plan/SKILL.md

@@ -75,7 +75,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -101,7 +101,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/humanizer/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: plastic-humanizer
+description: Use to clean authored prose so it reads human and clutter-free. Removes AI tells and slop from a document, spec, outcome, README, report, or release note. Use when the user says "humanize", "de-slop", "remove the AI tells", or "clean up the wording". For documents, not for every chat reply, and not for code.
+---
+
+# Humanizer
+
+Make writing read like a person wrote it: plain, direct, low-clutter. Run this as a pass over authored prose (specs, outcomes, README, reports). Do not run it on code or on every chat turn.
+
+## Lead (house style)
+Reframe your answers and any questions you have for me like you are speaking to a well-educated non-English native person. Reduce slang, and rarely used words and terms in the general communication. And cut all the fancy words from explanations. Technical terms and concepts are fine and need no gloss.
+
+## Voice
+Answer like a busy bartender or a senior support engineer who has seen almost every ticket. Help fast, give the fix first, earn the tip.
+
+## Job 1 - remove these surface tells
+1. Em-dashes and en-dashes - use a comma or a full stop.
+2. "Not X but Y" (and "it's not just X, it's Y").
+3. Rule of three - three items only for rhythm.
+4. Hype / AI words - delve, robust, comprehensive, seamless, leverage, crucial, unlock, landscape.
+5. Filler openers / signposting - "It's worth noting", "It's important to", "Let's dive in".
+6. Hedging pile-up - might, could, perhaps, generally, when not needed.
+7. Sycophancy - "Great question", "You're absolutely right".
+8. Over-bolding - bold only what carries weight.
+
+## Job 2 - fix the structure
+- Lead with the one main point.
+- Cut sentences that only restate.
+- Pick concrete words over abstract ones.
+- Match the user's voice when samples of their writing exist.
+
+## Process
+Write, check once against the rules above, then send. On documents, run this pass last.
+
+## Length
+Keep it short. If a sentence does not help the reader, cut it.
+
+## More
+For before/after examples, read `references/examples.md`. To make the house style always-on in chat, see `references/always-on-snippet.md`. The full 33-pattern catalog and the research behind this skill live in intent 92's `resources/`. They are background and are not loaded here.

package/skills/humanizer/evals/evals.json

@@ -0,0 +1,70 @@
+{
+  "skill_name": "plastic-humanizer",
+  "notes": "Intent 92. Cleans authored prose: removes 8 surface tells and applies structural levers (one point, cut restatement, concrete words, match voice). Triggers on document-cleanup asks, not on code. Runner is intent 76; assertions are human for now.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "trigger",
+      "set": "validation",
+      "prompt": "Humanize this README - it reads like AI wrote it.",
+      "expected_output": "Selects plastic-humanizer and runs the cleanup pass over the document.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is selected for a document-cleanup request",
+          "observed": "description triggers on 'humanize' / 'reads like AI' for a document",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "trigger",
+      "set": "validation",
+      "prompt": "Clean up the wording in this spec.",
+      "expected_output": "Selects plastic-humanizer and cleans the spec prose.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is selected for 'clean up the wording'",
+          "observed": "description triggers on 'clean up the wording'",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "non-trigger",
+      "set": "validation",
+      "prompt": "Fix the failing test in foo.rb.",
+      "expected_output": "Does NOT select plastic-humanizer; this is a code task, not prose cleanup.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is not selected for a code task",
+          "observed": "description scopes the skill to documents, not code",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "scope": "output",
+      "set": "validation",
+      "prompt": "Given a slop sample: 'It's worth noting that this is not just a fix, but a comprehensive, robust, and seamless improvement that will unlock real value.' Humanize it.",
+      "expected_output": "Cleaned text has no em-dashes and none of the 8 tells, leads with one point, and drops restatement. For example: 'This fix makes X faster.'",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "output drops the 8 tells, leads with one point, cuts restatement",
+          "observed": "no em-dashes; no 'not X but Y'; no rule-of-three; no hype words; no filler opener; one load-bearing point",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/humanizer/references/always-on-snippet.md

@@ -0,0 +1,9 @@
+# Always-on chat style (copy-paste)
+
+Paste this into your global `CLAUDE.md` (applies to all projects) or a project `AGENTS.md` (one project). It keeps the chat style on at near-zero cost. The full cleanup for documents is the `plastic-humanizer` skill.
+
+```
+Reframe your answers and any questions like you are speaking to a well-educated person who is not a native English speaker. Reduce slang and rarely used words. Cut fancy words from explanations. Technical terms and concepts are fine.
+
+Answer like a busy bartender or a senior support engineer who has seen almost every ticket: help fast, give the fix first, earn the tip.
+```