@g3nomaly/skills 1.0.0 → 1.0.1

package/dist/plugins/workflow/skills/sync/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Sync"
-  short_description: "Merge a reviewed phase, record its decisions and terms, and close it"
-policy:
-  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/worktree/SKILL.md

@@ -1,38 +0,0 @@
----
-name: worktree
-description: Set up, merge and remove the git worktrees that tasks are worked in, one per task on its own branch. Use when a task is about to be started, when a finished phase is being merged, when worktrees are left over, or when another skill needs a worktree.
-disable-model-invocation: false
----
-
-Every task gets its own **worktree**, a second checkout on its own branch, so agents working side by side never share a working directory and a half-finished task never dirties the checkout the user is in.
-
-## Names
-
-| Thing | Pattern | Example |
-|---|---|---|
-| Phase branch | `<type>/<plan>-<phase>` | `feature/auth-rework-01-schema` |
-| Task branch | `<worktree_type>/<task id>-<slug of the title>` | `feature/TASK-012-session-table-migration` |
-| Worktree folder | `../<repo folder>.worktrees/<task id>` | `../g3n.worktrees/TASK-012` |
-
-`worktree_type` comes from the task's frontmatter. The phase branch takes the type most of its tasks carry. The worktree folder sits beside the repository, outside it, so no search or build inside the repo walks into it.
-
-## Set up
-
-Run the commands under **Set up** in [`references/git-commands.md`](references/git-commands.md).
-
-- **Branch from the phase branch**, so a task sees the tasks it depends on once they are merged. A task whose `depends_on` names a task not merged yet branches from that task's branch instead.
-- **Install inside the worktree.** Dependencies are not shared between checkouts.
-- **An existing worktree for the task is reused.** `git worktree list` shows it. This is the normal case for a task sent back from review.
-
-## Merge
-
-Run the commands under **Merge** in [`references/git-commands.md`](references/git-commands.md).
-
-Run them from the main checkout, one task at a time, in the order the phase lists its tasks. `--no-ff` keeps one merge commit per task, which is what lets a single task be reverted later.
-
-## Remove
-
-Run the commands under **Remove** in [`references/git-commands.md`](references/git-commands.md).
-
-- **Only after the merge.** `git branch -d` refuses an unmerged branch, and that refusal is the safety net. Leave `-D` and `--force` to the user.
-- **A worktree with uncommitted changes stays.** Report it and let the user decide.

package/dist/plugins/workflow/skills/worktree/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Worktree"
-  short_description: "Set up, merge and remove one git worktree per task"
-policy:
-  allow_implicit_invocation: false

package/dist/plugins/workflow/skills/worktree/references/git-commands.md

@@ -1,27 +0,0 @@
-# Git commands
-
-The commands behind each section of the [`worktree`](../SKILL.md) skill. The names follow its **Names** table. Swap in the real plan, phase and task.
-
-## Set up
-
-```bash
-git switch -c feature/auth-rework-01-schema        # once per phase, from the base branch
-git worktree add -b feature/TASK-012-session-table-migration \
-  ../g3n.worktrees/TASK-012 feature/auth-rework-01-schema
-cd ../g3n.worktrees/TASK-012 && bun install
-```
-
-## Merge
-
-```bash
-git switch feature/auth-rework-01-schema
-git merge --no-ff feature/TASK-012-session-table-migration
-```
-
-## Remove
-
-```bash
-git worktree remove ../g3n.worktrees/TASK-012
-git branch -d feature/TASK-012-session-table-migration
-git worktree prune
-```

package/dist/plugins/writing/.claude-plugin/plugin.json

@@ -1,7 +0,0 @@
-{
-  "name": "writing",
-  "description": "How to write skills, hooks and tasks that an agent can follow.",
-  "version": "0.1.0",
-  "license": "UNLICENSED",
-  "skills": ["./skills/writing-great-hooks", "./skills/writing-great-skills", "./skills/writing-great-tasks"]
-}

package/dist/plugins/writing/skills/writing-great-hooks/SKILL.md

@@ -1,192 +0,0 @@
----
-name: writing-great-hooks
-description: How to write hooks — the self-contained scripts that carry deterministic work, both a skill's own hooks/ scripts and the lifecycle hooks the harness fires from settings.json. Use when adding, reviewing, or debugging a hook script, when a skill needs a query/filter/rank helper, when wiring UserPromptSubmit, PreToolUse, PostToolUse or Stop, or when the user asks how hooks should be written, registered, or documented.
-disable-model-invocation: false
----
-
-A **hook** is a script that carries the part of a job which must come out the same every time. Where prose _steers_ the agent, a hook _replaces_ it: parsing, filtering, ranking, counting and formatting run as code, so the answer does not vary with the run. It is the strongest form of predictability available — reach for one wherever the work is mechanical.
-
-Two kinds. Everything below applies to both unless a section says otherwise.
-
-| Kind | Lives in | Fired by | Reach for it when |
-|---|---|---|---|
-| **Skill hook** | `<skill>/hooks/`, beside its `SKILL.md` | the agent, because the skill told it to | a skill needs a query, filter, or ranking answered the same way every run |
-| **Lifecycle hook** | anywhere `settings.json` can name it | the harness, at a fixed event | something must happen on every prompt, tool call, or stop, with no agent deciding to call it |
-
-The distinction that matters: a **skill hook** answers a question the agent chose to ask, so it can only ever inform. A **lifecycle hook** fires whether the agent wants it or not, which is what lets it inject context, block a tool call, or refuse a stop.
-
-## The two invariants
-
-Everything else here is negotiable. These are not.
-
-**Self-sufficient.** One file, zero dependencies. No `package.json`, no shared `lib/`, no `import` of a sibling, no install step — copy the file anywhere on the machine and it runs. When two hooks need the same parser or the same types, **each embeds its own copy**. That duplication is the price of the invariant and is paid on purpose: say so in a comment at the top of the shared block, and keep the copies in sync when the format changes. A hook that needs an install is a hook that fails the one time it matters.
-
-**Co-located.** A **skill hook** lives in `hooks/`, directly beside the `SKILL.md` that documents it — never in a repo-wide `scripts/` folder, never one directory up. The script and its instructions move, get read, and get reviewed as one unit. A hook nobody can find from the skill is a hook the agent will re-implement inline. A **lifecycle hook** belongs to the project rather than to a skill, so it lives in `.claude/hooks/` and is co-located instead with the `settings.json` entry that names it: registration and script are edited together or not at all.
-
-```
-<skill>/
-├── SKILL.md          # documents when to reach for each hook
-└── hooks/
-    ├── do-one-thing.ts
-    └── do-another-thing.ts
-```
-
-One hook does one thing and is named for it, in verb-first kebab-case: `get-top-priority-task.ts`, not `tasks.ts --mode=priority`. A flag that changes _what the script is for_ should have been a second file; a flag that narrows _the same job_ belongs where it is.
-
-## The skill-hook contract
-
-A **skill hook** is called by an agent that will not read a stack trace to work out what happened. Make the interface answer for itself.
-
-- **stdout is data; stderr is prose.** JSON on stdout, nothing else — no progress lines, no banners, no trailing "Done!". Every human-readable word goes to stderr. An agent piping stdout into a parser must never get a surprise.
-- **Exit code carries the verdict.** `0` ran, non-zero could not. Whether "nothing matched" is a failure is the script's decision and must be stated in its header: a hook that must return exactly one thing exits `1` with a reason on stderr; a search hook prints `[]` and exits `0`, because empty is a real answer.
-- **Flags, not positions**, and every flag defaults to the value that works from the repo root. `--index tasks/index.yaml` is a default, not a requirement. Reserve `--pretty` for indented JSON so the compact form stays pipeable.
-- **Deterministic output.** Every sort has an explicit final tie-breaker, so the same input yields the same order on every run. A hook whose output shuffles has given back the variance it existed to remove.
-- **Validate at the boundary, fail loudly.** Parse the input yourself, reject anything outside the documented shape, and name the offending line or field in the message. A loud failure costs one turn; a silent default costs the agent acting on a garbled answer.
-- **Read-only by default.** A hook that answers a question must not change state. If a hook has to write, say so in its first line of documentation and in the skill's table.
-
-## The lifecycle-hook contract
-
-A **lifecycle hook** never sees a flag. The harness pipes it a JSON **event payload** on stdin and reads three things back: the exit code, stderr, and — on exit `0` — stdout.
-
-Every payload carries the same four fields, plus whatever its event adds:
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/you/.claude/projects/<slug>/<session>.jsonl",
-  "cwd": "/home/you/project",
-  "hook_event_name": "PreToolUse"
-}
-```
-
-Three exit codes, and the meaning of the middle one is the whole reason lifecycle hooks exist:
-
-| Exit | Means | Where stderr goes |
-|---|---|---|
-| `0` | ran clean | transcript only; stdout handling is per-event |
-| `2` | **blocking error** — the hook is exercising its veto | to the agent, as the reason |
-| other | non-blocking error | to the user; the run continues regardless |
-
-Exit `2` does something different at every event — it erases a prompt, denies a tool call, or refuses a stop — so it is documented per event, not here.
-
-For anything richer than a veto, print a JSON object on stdout and exit `0`. Four fields work at every event:
-
-- **`continue`** (default `true`) — `false` halts the agent outright, after this hook.
-- **`stopReason`** — the string shown to the user when `continue` is `false`.
-- **`suppressOutput`** — keep stdout out of the transcript.
-- **`systemMessage`** — a warning surfaced to the user.
-
-Each event adds its own `hookSpecificOutput` object on top. Those are the per-event skills below.
-
-_The harness is the authority on payload and output shapes, and they gain fields over time._ Confirm against the live `/hooks` view before relying on a field that changes behaviour.
-
-## Registering a lifecycle hook
-
-Registration is an array per event, each entry pairing an optional **matcher** with the commands to run:
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|MultiEdit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-types.ts",
-            "timeout": 60
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-- **`matcher` selects tools by name**, as a regex — `Edit|Write`, `Bash`, or omitted for every tool. Only `PreToolUse` and `PostToolUse` use it; `UserPromptSubmit` and `Stop` have no tool to match and take an entry with no matcher.
-- **Every matching entry runs, in parallel.** Two hooks matching the same tool both fire; neither sees the other's output. Never write one expecting to run after another.
-- **`$CLAUDE_PROJECT_DIR` resolves to the project root**, so registrations survive a different working directory. An absolute path outside the project is fine for a machine-wide tool.
-- **`timeout` is seconds, and the default is 60.** It bounds one command, and a hook that hits it is killed — a slow hook taxes every single event it is registered on.
-
-## The four events
-
-Each fires at a different moment and buys a different power. Read the one you are writing:
-
-| Event | Fires | What it can do | Skill |
-|---|---|---|---|
-| `UserPromptSubmit` | the user submits, before the agent reads it | inject context, rewrite the terms, reject the prompt | [`hook-user-prompt-submit`](../hook-user-prompt-submit/SKILL.md) |
-| `PreToolUse` | a tool is chosen, before it runs | allow, deny, or escalate the call to the user | [`hook-pre-tool-use`](../hook-pre-tool-use/SKILL.md) |
-| `PostToolUse` | a tool has finished | react to what happened; it cannot undo it | [`hook-post-tool-use`](../hook-post-tool-use/SKILL.md) |
-| `Stop` | the agent is about to end its turn | refuse the ending and say what remains | [`hook-stop`](../hook-stop/SKILL.md) |
-
-## The header block
-
-The agent frequently reads a hook before running it — the file has to explain itself without `SKILL.md` present. Directly under the shebang, a block comment with four parts:
-
-```ts
-#!/usr/bin/env bun
-/**
- * get-top-priority-task
- *
- * Returns the open task with the most urgent priority. Ties break by
- * creation order, so results are deterministic.
- *
- * Usage:
- *   ./get-top-priority-task.ts [--index tasks/index.yaml] [--pretty]
- *
- * Output:
- *   One task object as JSON on stdout; exit 1 with a message on stderr
- *   when there are no open tasks.
- */
-```
-
-Name, one paragraph of behaviour, real invocations, and the output shape with its exit codes. Anything a caller must know to use the script correctly goes here, not only in the skill. A **lifecycle hook** substitutes its event and matcher for the usage line, and states what each exit code makes the harness do.
-
-## Writing the script
-
-TypeScript on Bun, in this repo. The invariants force three specifics that look odd out of context, so comment them where they appear:
-
-- **`#!/usr/bin/env bun`** on line 1, so the file is directly executable. Still document `bun run hooks/<script>.ts` as an equivalent — the executable bit does not reliably survive a checkout, and that fallback is what keeps the hook runnable when it doesn't.
-- **`export {}` as the first statement.** Without a top-level import or export, TypeScript treats a `.ts` file as a global script, so several hooks in one folder collide on every shared name — duplicate `Task`, duplicate `main`, "cannot redeclare" on every constant. The marker scopes each file to itself.
-- **Hand-declared runtime globals** instead of `@types/node` or `bun-types`:
-
-  ```ts
-  declare const process: { readonly argv: string[]; exit(code?: number): never; cwd(): string };
-  declare const Bun: { file(path: string): { text(): Promise<string> }; stdin: { text(): Promise<string> } };
-  ```
-
-  This is what lets the file type-check with zero installs. Declare only the members used — a local `declare const` inside a module shadows a real ambient global rather than fighting it, so the file stays correct even in a package that _does_ have the types installed.
-
-Beyond that, ordinary production rules apply: `strict`-clean, no `any`, explicit types on every function that isn't a one-line local, errors handled rather than swallowed, and a single `main().catch(printError)` at the bottom so no rejection escapes.
-
-**A lifecycle hook runs with your credentials on input the agent influenced.** Treat every payload field as hostile: never interpolate one into a shell string, resolve any path before comparing it, and decide what an unrecognised shape does before shipping.
-
-## Documenting hooks in the skill
-
-The hook's own header says _what it does_; `SKILL.md` says _which one to reach for_. Give the skill a table with one row per hook:
-
-| Hook | Does | Use it when |
-|---|---|---|
-
-Then state, once, the facts shared by all of them: how they're invoked, what the common flags default to, and where their behaviour deliberately differs (one returns a single object, another an array; one filters by status implicitly, another doesn't). Every flag named in the table must exist in the script, and every script in `hooks/` must appear in the table.
-
-A **lifecycle hook** is documented by its registration instead: the event, the matcher, and what each exit code makes the harness do. A reader who cannot predict when it fires cannot debug it.
-
-## When not to write a hook
-
-**A hook computes; it never decides.** Ranking open tasks by priority is computation — the rule is fixed and the tie-breaker is written down. Deciding whether a task is worth doing today is judgement, and judgement in code is a rule nobody can see, argue with, or override. If the answer depends on context the script can't read, it belongs in the skill's prose.
-
-Nor is a hook worth writing for work the agent already does reliably in one step. Reading a single file, grepping for a string, or reformatting a small blob is cheaper inline than as a script that must be maintained, documented, and kept in sync.
-
-**A lifecycle hook additionally has to earn its event.** It runs on every prompt, every matching tool call, or every stop, forever, whether or not this session cares — so cost and false positives are paid continuously while the benefit arrives occasionally. A rule that matters only sometimes belongs in prose the agent reads when it applies.
-
-## Failure modes
-
-- _Hidden dependency._ An `import` of a sibling module, a `package.json` in `hooks/`, an assumed global install. The hook works in the repo it was written in and nowhere else, and the breakage surfaces at the call site as a stack trace the agent has no context for.
-- _Silent fallback._ Malformed input quietly coerced to a default — a missing field read as `""`, an unparseable line skipped. The script returns a confident wrong answer, and the agent acts on it. Throw instead, naming the input.
-- _Chatty stdout._ A log line, a warning, or a human sentence mixed into the JSON. Every caller that parses stdout breaks at once, and on a lifecycle hook the stray text is read as the hook's whole answer.
-- _Ambiguous exit._ Exiting `0` on "found nothing" in a hook whose contract is "returns one", or `1` on an empty search result. The caller cannot distinguish "no answer" from "broken", so it guesses. On a lifecycle hook, the near-miss is worse: `1` where `2` was meant is a veto that silently never happened.
-- _Unstable order._ A sort with no final tie-breaker, or output built from an unordered map. Two runs disagree and the skill's predictability is gone at exactly the point it was supposed to be guaranteed.
-- _Doc drift._ A flag renamed in the script but not the table, a hook added without a row, a registration whose matcher no longer matches the tools it names. The documentation is the interface; an edit to the script that skips it is half an edit.
-- _Judgement in code._ A weighting, threshold, or preference hardcoded into a hook where the skill should have stated the rule in prose for the agent to apply.
-- _Event tax._ A hook doing real work — a full typecheck, a network call — on an event that fires constantly. Every prompt or tool call now waits on it. Scope by matcher, exit early on the common case, and keep the slow path behind a cheap test.

package/dist/plugins/writing/skills/writing-great-hooks/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Writing Great Hooks"
-  short_description: "Self-contained scripts that carry deterministic work, in a skill or on a lifecycle event"
-policy:
-  allow_implicit_invocation: false

package/dist/plugins/writing/skills/writing-great-skills/GLOSSARY.md

@@ -1,201 +0,0 @@
-# Glossary — Building Great Skills
-
-The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md).
-
-The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
-
-**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
-
-## Predictability
-
-The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
-
-_Avoid_: consistency, reliability, robustness, output-determinism
-
-## Invocation
-
-How a skill is reached — and the two loads you pay for the choice.
-
-### Model-Invoked
-
-A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
-
-_Avoid_: ability, tool, capability
-
-### User-Invoked
-
-A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
-
-_Avoid_: procedure, workflow, command
-
-### Description
-
-The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
-
-_Avoid_: frontmatter, summary
-
-### Context Pointer
-
-A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
-
-_Avoid_: link, reference, import
-
-### Context Load
-
-The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
-
-_Avoid_: token cost, context bloat
-
-### Cognitive Load
-
-The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
-
-_Avoid_: human index, burden, overhead
-
-### Router Skill
-
-A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
-
-_Avoid_: dispatcher, menu, registry, index, router procedure
-
-### Granularity
-
-How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
-
-_Avoid_: chunking, modularity
-
-## Information Hierarchy
-
-How a skill's content is arranged, and how far down the ladder each piece sits.
-
-### Information Hierarchy
-
-A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
-
-- **Steps** — in-file, primary
-- **Reference**, in-file — secondary
-- **Reference**, disclosed — behind a **context pointer**
-
-A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
-
-_Avoid_: structure, organization, layout
-
-### Steps
-
-The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
-
-_Avoid_: workflow, instructions, choreography
-
-### Reference
-
-Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
-
-_Avoid_: supporting material, docs, background
-
-### External Reference
-
-**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
-
-_Avoid_: doc, resource, knowledge base
-
-### Progressive Disclosure
-
-Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
-
-_Avoid_: lazy loading, chunking
-
-### Co-location
-
-Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
-
-_Avoid_: grouping, clustering, cohesion
-
-### Sprawl
-
-_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
-
-_Avoid_: bloat, length, size, verbosity
-
-## Steering
-
-The levers that shape the agent's runtime behaviour toward **Predictability**.
-
-### Branch
-
-A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
-
-_Avoid_: path, case, fork
-
-### Leading Word
-
-A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
-
-A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
-
-_Avoid_: keyword, term, motif
-
-### Completion Criterion
-
-The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
-
-_Avoid_: done condition, exit condition, stopping rule
-
-### Legwork
-
-The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
-
-_Avoid_: scope, effort, diligence, coverage
-
-### Post-Completion Steps
-
-The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
-
-_Avoid_: horizon, fog of war, lookahead
-
-### Premature Completion
-
-_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
-
-_Avoid_: premature closure, the rush, rushing, shortcutting
-
-### Negation
-
-_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
-
-_Avoid_: ironic rebound, don't-prompting, the pink elephant
-
-## Pruning
-
-Keeping a skill lean — each remedy paired with the failure it cures.
-
-### Single Source of Truth
-
-The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
-
-_Avoid_: home, canonical location
-
-### Duplication
-
-_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
-
-_Avoid_: repetition, redundancy
-
-### Relevance
-
-Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
-
-_Avoid_: load-bearing, staleness, freshness
-
-### Sediment
-
-_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
-
-_Avoid_: accretion, bloat, cruft, rot
-
-### No-Op
-
-_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
-
-A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
-
-_Avoid_: redundant instruction, restating the obvious, belaboring

package/dist/plugins/writing/skills/writing-great-skills/SKILL.md

@@ -1,92 +0,0 @@
----
-name: writing-great-skills
-description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
-registryDependencies: [emphasise, writing-great-hooks]
-disable-model-invocation: false
----
-
-A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
-
-**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
-
-## Invocation
-
-Two choices, trading different costs:
-
-- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
-- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
-
-Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
-
-When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.
-
-## Writing the description
-
-A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:
-
-- **Front-load the skill's leading word** — the description is where it does its invocation work.
-- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
-- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
-
-## Information hierarchy
-
-A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
-
-1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
-2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
-3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.)
-
-A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
-
-Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
-
-**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
-
-Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
-
-## When to split
-
-**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:
-
-- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it.
-- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task.
-
-## Pruning
-
-Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.
-
-Check every line for **relevance**: does it still bear on what the skill does?
-
-Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.
-
-## Leading words
-
-A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.
-
-It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.
-
-Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include:
-
-- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop).
-- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
-
-You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.
-
-## Emphasis
-
-Bold, italics, and backticks carry fixed meanings across every skill here, and all three work by scarcity. Use the `/emphasise` skill when writing or editing them.
-
-## Hooks
-
-Where work is mechanical, a script replaces the prose — either a script the skill ships in `hooks/`, or one the harness fires from `settings.json` at a lifecycle event. Use the `/writing-great-hooks` skill when adding, documenting, registering, or invoking one.
-
-## Failure modes
-
-Use these to diagnose issues the user may be having with the skill.
-
-- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).
-- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
-- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
-- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
-- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
-- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

package/dist/plugins/writing/skills/writing-great-skills/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Writing Great Skills"
-  short_description: "Principles for predictable skills"
-policy:
-  allow_implicit_invocation: false