@sassywares/skills 0.5.10 → 0.5.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",

package/skills/sassy-skill/SKILL.md

@@ -12,7 +12,7 @@ disable-model-invocation: true
 
 # Sassy Skill
 
-**Outcome:** a well-formed Agent Skill at a location the user chose, or an existing skill improved and re-verified. The harness loads it with no diagnostics.
+**Outcome:** a well-formed Agent Skill at a location the user chose, an existing skill improved and re-verified, or a report on one — and the harness loads it with no diagnostics.
 
 **Modes.** `mode:create` writes a new skill. `mode:retune` changes the smallest thing that fixes a named failure in an existing skill. `mode:verify` checks an existing skill against the checklist and reports — it edits nothing. Omitted, detect it from the argument: something that already resolves to a skill directory is `retune`, or `verify` when the user only asked whether it is any good; anything else is `create`. State the mode you picked and why; when both are plausible, ask instead of guessing.
 
@@ -20,11 +20,23 @@ disable-model-invocation: true
 
 **Scope:** skills only — not extensions, packages, or prompt templates.
 
+## One mode, one reference
+
+Each mode's mechanics live in its own file. Read the one you were dispatched to — **and only that one**. A `create` never reads `retune`'s failure map, and a `verify` never picks up a fix from it: that adjacency is exactly how a read-only check turns into an edit.
+
+| Mode | Load | It ends with |
+|---|---|---|
+| `create` | `references/create.md` | a new skill on disk, installed and verified |
+| `retune` | `references/retune.md` | the smallest edit that kills one named failure, re-verified |
+| `verify` | `references/verify.md` | a report, and no file touched |
+
+Everything below is shared by all three: the location table, pi's rules, the shape rule, the checklist, and the verification run. Read it once, then your one reference.
+
 ## pi's rules (the essentials)
 
 - A skill is a **directory containing `SKILL.md`**. Discovered recursively.
 - **Name:** lowercase letters, numbers, hyphens; no leading/trailing/consecutive hyphens; ≤64 chars. Match the directory name.
-- **Description:** required, ≤1024 chars. Pi advertises name + description at startup; the body loads only when the skill is used. The description decides whether the skill ever fires — write **what it does and when to use it**.
+- **Description:** required, ≤1024 chars. Pi advertises name + description at startup; the body loads only when the skill is used, so the description alone decides whether the skill ever fires. Write **what it does and when to use it**, with concrete verbs and the words a user would actually say — "can't trigger" is almost always a description that named the topic and never the moment.
 - **Frontmatter fields:** `name`, `description` (required); optional `license`, `compatibility`, `metadata`, `allowed-tools`, `disable-model-invocation`.
 - Use `disable-model-invocation: true` for skills that should run only via explicit `/skill:name`.
 - **Reference other skills by name, never by absolute path.** The suite can live in `~/.agents/skills/`, a project `.agents/skills/`, or inside `node_modules/`, so "load the sassy-commit skill" is portable where a `~/…` path is not. Name a bundled file as "the sassy-setup skill's `references/config.md`".
@@ -47,46 +59,44 @@ Internal is the only one that ships to everyone. Never choose it silently: once
 
 Paths in the table are the defaults. Harnesses also read `skills` arrays in settings and installed packages, so a skill may live elsewhere — write down where it actually went.
 
-## Shape rule — the lean rule
+## Shape rule — split on outcomes, not on topics
 
-- **Default to one `SKILL.md`.**
-- Add `references/` **only** for content that is **conditionally read** (or genuinely bulky and only sometimes needed). A reference that is read on *every* run saves nothing and may cost a little.
-- Keep `SKILL.md` an index: outcome → hard rules → workflow → explicit pointers ("read `references/x.md` before doing Y").
-- Never bury conditional detail in a monolithic `SKILL.md`.
-
-## Workflow
-
-1. **Intake.** Settle the mode (above), then what the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. In `mode:retune`, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope). In `mode:verify`, read it, run the checklist and Verify, report, and stop without writing.
-2. **Choose the shape.** Single file, or `SKILL.md` + `references/` per the rule above.
-3. **Write the frontmatter.** A description that states both what and when.
-4. **Write the body.** Outcome, a hard-rules table, the workflow, and reference pointers. Plain English. Structured output where the skill returns a result. Match this setup's house style.
-5. **Self-check** against the checklist below.
-6. **Install and verify.** Place it at the right path, run `/reload`, confirm no startup diagnostics, and test `/skill:<name>`.
+- **One `SKILL.md` is the default, but it is a decision, not a reflex.** Length never decides the shape; the paths do.
+- **Split whenever the skill branches into paths that end differently.** A mode, trigger, or branch that writes a different thing, forbids a different thing, or is never needed in the same run as its sibling gets its own `references/<path>.md` — **even at three paragraphs**. How small each path is does not matter: what matters is that a model running path A never reads path B's instructions next to A's. Divergent outcomes sharing one file bleed into each other, and the bleed looks like helpfulness until it has already written the wrong thing. Think ahead when you write it, not after the first misfire. This skill is shaped by its own rule.
+- **Never split a shared surface.** What every path needs — ids, board or table values, hard rules, API quirks, house style — stays in `SKILL.md`, or each path pays to load it and they drift apart. One reference per **outcome**, never one per **section**: `references/` holding five short topic files is the oversplit, and it makes routing vaguer, not sharper.
+- **`SKILL.md` becomes routing.** State the dispatch explicitly — a table naming exactly one reference per path, plus "read that one only". That sentence is what prevents the bleed; a pointer buried in a paragraph does not.
+- A reference that is read on *every* run saves nothing and may cost a little, so it belongs in the body.
+- Keep `SKILL.md` an index: outcome → hard rules → workflow → explicit pointers ("read `references/x.md` before doing Y"). Never bury path-specific detail in a monolithic file.
 
 ## Self-check checklist
 
+The gate for a new or edited skill, and the instrument in `mode:verify`.
+
 - [ ] `name`: lowercase/hyphens, ≤64, matches the directory.
 - [ ] `description`: states what **and** when, ≤1024, not vague.
 - [ ] Frontmatter is valid YAML with the required fields.
 - [ ] Every `references/…` path exists and is pointed to explicitly in the body.
+- [ ] Each outcome path that ends differently has its own reference, and the body dispatches to exactly one of them per run.
+- [ ] No reference exists merely because its content was a separate section — that is oversplitting, not shaping.
 - [ ] The body is lean; no always-read detail needlessly hidden in a reference.
 - [ ] No secrets, and no capability the skill cannot actually use.
 
-## Retune
-
-In `mode:retune`, change the **smallest** thing that fixes the named failure:
-
-- **Won't trigger** → rewrite the description (what + when, concrete verbs).
-- **Too long / bloated** → extract conditional content to `references/`, or delete what never gets used.
-- **Wrong or stale steps** → correct the workflow against the current tree.
-- **Wrong scope** → move it between internal, project, and user. Moving into the suite is a release; moving out of it means the next release drops the skill for everyone.
-
-Re-verify after any retune.
-
-## Verify
-
-Run this at the end of `create` and `retune`, and as the whole job in `mode:verify`.
+## Verification — how every mode ends
 
 - `/reload`.
 - Check pi's startup output for warnings about the skill.
 - Run `/skill:<name>` and confirm it loads and behaves.
+
+`create` and `retune` are not finished until this passes; `verify` exists to run it and report.
+
+## Hard rules
+
+| Rule | Requirement |
+|------|-------------|
+| Ask before writing | The location — internal, project, or user — is the user's call, never the cwd's. State the mode you inferred. |
+| Verify writes nothing | `mode:verify` ends with a report. If you spot a fix while verifying, name it and let the user ask for the retune. |
+| Retune is minimal | One named failure, the smallest change that kills it. No drive-by rewrites, no tidy-ups nobody asked for. |
+| Split by outcome | Divergent paths get their own reference even when tiny; shared surfaces stay in the body. |
+| Name skills, not paths | Reference another skill by name so the suite stays portable across install locations. |
+| Internal is a release | Putting a skill in the suite ships it to every consumer on `main`. Never choose it silently. |
+| Nothing untestable | No secrets, and no capability the skill cannot actually perform. |

package/skills/sassy-skill/references/create.md

@@ -0,0 +1,48 @@
+# Mode: create — write a new skill
+
+Read the skill's shared sections first (locations, pi's rules, shape rule, checklist). This file is the write side only.
+
+## 1. Intake
+
+Settle three things by asking, not inferring:
+
+- **What it does** — the one outcome, stated as a result ("a merged PR", "a filed ticket", "a plan on disk"), not as an activity.
+- **When it fires** — the words a user will actually say. These become the description's *when* half.
+- **Where it lives** — internal, project, or user, per the location table. Ask; the cwd proves nothing.
+
+If any of the three is missing, ask before writing a file. A skill authored on a guess is the one that gets retuned next week.
+
+## 2. Choose the shape — enumerate the outcome paths first
+
+List the ways a run can end (for example: file / comment / move a state; plan / implement / ship; create / retune / verify). Then apply the shape rule:
+
+- A path that ends differently, forbids something different, or is never needed alongside its sibling → its own `references/<path>.md`, however short.
+- What every path needs → the body.
+- Then write the dispatch table in the body that names **exactly one** reference per path, and the sentence that says read only that one.
+
+Two paragraphs of route-specific instruction are worth their own file; a shared field table is not worth splitting.
+
+## 3. Frontmatter
+
+`name` matches the directory. `description` states what and when, ≤1024 chars, in the user's vocabulary. Add `disable-model-invocation: true` when the skill should only run via `/skill:<name>`, and an `argument-hint` when it takes one.
+
+Do not put workflow detail in the description — it decides triggering, not execution.
+
+## 4. Body
+
+House shape, in this order:
+
+1. **Outcome** — one sentence, a result.
+2. **Hard rules** — a table of the few invariants that, if broken, make the output wrong regardless of how the steps went.
+3. **Workflow** — numbered steps a competent agent can follow without re-deriving them, with the reference pointer for each path.
+4. **Pointers** — "read `references/x.md` before doing Y", never a bare file list.
+
+Plain English, no filler. Where the skill returns a result, give the shape of that result so two runs look alike.
+
+## 5. Place and install
+
+- **Internal:** `skills/<name>/` in the sassy-skills repo, named `sassy-<name>`; then `scripts/sync.sh` — it commits, bumps the patch version, tags, and publishes. Say that this ships to everyone before you do it.
+- **Project:** `<repo>/.agents/skills/<name>/`, prefixed with the project so it cannot collide with a suite skill or a harness built-in; then commit it.
+- **User:** `~/.agents/skills/<name>/`. Nothing gates it, so check it actually works before trusting it.
+
+Then run the skill's Verification section: `/reload`, no startup warnings, `/skill:<name>` behaves. A skill that has never been invoked has not been written.

package/skills/sassy-skill/references/retune.md

@@ -0,0 +1,33 @@
+# Mode: retune — the smallest fix for one named failure
+
+Read the skill's shared sections first (locations, pi's rules, shape rule, checklist). This file is the failure map.
+
+## 1. Name the failure before touching anything
+
+Read the skill and say which of these it is, in one line. "It feels long" is not a failure; "it fires on status moves too" is.
+
+## 2. Failure → smallest fix
+
+| Named failure | The fix |
+|---|---|
+| **Won't trigger** | Rewrite the description: what + when, concrete verbs, the user's own words. Not the body. |
+| **Fires when it shouldn't** | Tighten the description's *when* half, or add `disable-model-invocation: true` if it is an explicit-only skill. |
+| **One path's rules bleed into another's** (a mode doing the neighbouring mode's job) | A shape bug, not a wording bug: split the divergent outcomes into `references/`, one file per path, and give the body a dispatch table naming exactly one file per mode. Rewording the paragraph does not fix adjacency. |
+| **Too long / bloated** | Extract conditional content to `references/`, or delete what never gets used. Never delete a hard rule to save lines. |
+| **Wrong or stale steps** | Correct the workflow against the current tree — read the files the steps name before trusting them. |
+| **Wrong scope** | Move it between internal, project, and user. Moving into the suite is a release; moving out means the next release drops the skill for everyone. |
+| **Oversplit** (five topic files, vague routing) | Fold shared surfaces back into the body and keep one reference per outcome. |
+
+If the request names no failure, ask for one. A retune without a failure is a rewrite with extra steps.
+
+## 3. Change that thing only
+
+- One failure, the smallest edit that kills it, no drive-by rewrites or tidy-ups.
+- Re-read the surrounding lines so the fix does not contradict a rule elsewhere in the file.
+- If the fix moves content into `references/`, the body must dispatch to it by name and say to read only that one.
+
+## 4. Ship and re-verify
+
+- Internal skill → `scripts/sync.sh` (commit, bump, tag, publish; say so before running it).
+- Project or user skill → committed or written in place, as its location requires.
+- Then run the skill's Verification section: `/reload`, no startup warnings, `/skill:<name>` behaves. A retune that was never invoked has not been verified.

package/skills/sassy-skill/references/verify.md

@@ -0,0 +1,41 @@
+# Mode: verify — read, judge, report, change nothing
+
+Read the skill's shared sections first (locations, pi's rules, shape rule, checklist). This file is the read-only sweep.
+
+**No writes. Not one.** No edits, no renames, no moving files between locations, no version bumps, no `scripts/sync.sh`. A verify run that "just fixes a typo while it is there" has become a retune without a named failure, and the user loses the report they asked for.
+
+## 1. Read the whole skill as the harness will
+
+- `SKILL.md`, then every file under `references/` — you cannot judge routing without seeing what it routes to.
+- Check the frontmatter parses and the directory name matches `name`.
+- If it ships from the suite or a package, note the pinned version: verification is against what consumers actually got.
+
+## 2. Run the checklist
+
+Walk the shared **Self-check checklist** item by item. For each, the evidence is the file, not an impression:
+
+- Description: quote it and count the characters; does it name the *moment* it fires?
+- References: every pointer resolves to a file that exists, and the body says read only one at a time.
+- Shape: do the divergent paths sit in separate files, and is each shared surface back in the body?
+- Leanness: is anything in the body only sometimes needed, or anything in a reference read on every run?
+
+## 3. Run the skill, if it is installed
+
+`/reload`, then check pi's startup output for warnings, then `/skill:<name>`. Quote what it did. If it cannot be invoked here — different harness, uninstalled, needs credentials — say that plainly instead of implying a pass.
+
+## 4. Report in one shape
+
+```md
+**<skill name> — <verdict: sound | needs a retune | malformed>**
+
+**Passes**
+- Each checklist item that held, with the evidence in a clause.
+
+**Fails**
+- `<checklist item>`: what is wrong, `path:line`, and the one-line fix a retune would make.
+
+**Unverified**
+- What you could not check here, and why.
+```
+
+Then stop. Name the retunes you would make; do not make them. If the user wants one, that is a new run in `mode:retune`, with the failure named.