write-skills 0.3.1 → 0.4.1

package/README.md

@@ -1,64 +1,134 @@
 # write-skills
 
-Fifteen agent skills for writing. Each skill works alone. Install one skill or all of them.
+[![npm](https://img.shields.io/npm/v/write-skills.svg)](https://www.npmjs.com/package/write-skills)
+[![downloads](https://img.shields.io/npm/dm/write-skills.svg)](https://www.npmjs.com/package/write-skills)
+[![ci](https://github.com/adhamhaithameid/write-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/adhamhaithameid/write-skills/actions/workflows/ci.yml)
 
-## Skills
+[![stars](https://img.shields.io/github/stars/adhamhaithameid/write-skills.svg)](https://github.com/adhamhaithameid/write-skills/stargazers)
+[![license MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![install](https://img.shields.io/badge/install-npx%20skills%20add-blue.svg)](https://www.skills.sh/adhamhaithameid/write-skills)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](CONTRIBUTING.md)
+[![experiment](https://img.shields.io/badge/experiment-13%20clear%20%C2%B7%209%20thin%20%C2%B7%200%20fail-brightgreen.svg)](docs/EXPERIMENT.md)
+
+Twenty-two agent skills that fix how agents write. Each skill works alone. Install one skill or all of them.
+
+> The mission: the reading experience must never feel like hell. Every skill serves that.
+
+## Before and after
+
+Red is what the agent wrote before. Green is what the skill rules produced.
+
+**write-better**, a chat answer:
+
+```diff
+- Sure! I'd be happy to help. In order to boost your productivity, this
+- robust tool leverages cutting-edge caching for a seamless experience.
++ The tool caches your queries. A repeat query answers in 12 ms. A cold
++ query answers in 340 ms.
+```
+
+**write-compact**, the same answer in one line:
+
+```diff
+- Certainly! Let me explain. The issue you're experiencing is likely
+- caused by a misconfiguration of your authentication settings.
++ Auth fails. The token check reads the wrong claim. Fix in auth.ts line 40:
+```
+
+**write-pr**, a PR body:
+
+```diff
+- This PR makes several improvements to the authentication system and
+- cleans up a number of related issues that we noticed during testing.
++ Reject expired session tokens at login. The reset test fails on main
++ and passes here. Risk: two-way door, login only.
+```
+
+**write-jira**, a story:
+
+```diff
+- BE-1 Backend table (3)   BE-2 Upload endpoint (5)   WEB-1 Button (5)
++ One vertical story: POST /tasks/{id}/attachments saves the file, the
++ web view lists it. Points: 5. One table, one endpoint, one screen.
+```
+
+The full gallery covers all twenty-two skills in [docs/examples.md](docs/examples.md).
+
+## Why
+
+AI text is hard to read. Subjects sit far from their verbs. Nouns stack four deep. Databases want things and conversations eat their own tails. A 2026 study by NYU and UT Austin found these patterns across 14 models and tied them to how the models train. This set fixes the patterns at the source.
+
+It also gives the agent a shape for every text a developer writes: chat replies, commit messages, PR bodies, docs, tickets, reports, plans.
+
+## Quick start
+
+1. Install the set: `npx skills add adhamhaithameid/write-skills`
+2. Start a session and ask your agent to write anything.
+3. Watch the reply land on the first read.
+
+## The skills
+
+### Chat and replies
+
+| Skill | Use for |
+|---|---|
+| write-better | The general floor: reader levels, sentence rules, AI patterns, reader load. |
+| write-compact | Brief replies on request. The whole reply stays short. |
+| write-tldr | A short block at the end of a long answer: TLDR plus what was found. |
+| write-again | Rewrite the last output, explain a failed answer again, or refresh a stale doc. |
+| help-write | Ask in chat which skill fits the task; it routes and follows. |
+
+### Code
 
 | Skill | Use for |
 |---|---|
-| write-core | Chat answers, explanations, and notes. Reader levels, depth, sentence rules, AI patterns. |
-| write-compact | Brief replies on request, or explain a confusing reply again. |
-| write-docs | READMEs, tutorials, how-to guides, reference pages, explanations, RFCs, and documents an agent reads. |
-| write-pr | PR title and description from the change and the evidence. |
 | write-commit | Commit message from the staged diff and the repository history. |
+| write-pr | PR title and description from the change and the evidence. |
 | write-comments | Code comments that state intent, constraints, and invariants. |
 | write-review | Review comments on a diff: location, problem, fix. |
+
+### Product and planning
+
+| Skill | Use for |
+|---|---|
+| write-plan | A plan before work starts: goal, approaches, steps, risks. |
+| write-adr | Architecture decision records: context, decision, consequences. |
+| write-prd | Product requirements: problem, goals, testable requirements, metrics. |
 | write-jira | Jira epics, stories, and story points from a plan. |
 | write-issue | GitHub issues and bug reports with reproduction steps. |
 | write-release | Release notes from git history. |
-| write-report | Status updates, incident reports, and findings for a decision-maker. |
+
+### Knowledge
+
+| Skill | Use for |
+|---|---|
+| write-docs | READMEs, tutorials, reference pages, RFCs, and documents an agent reads. |
 | write-summary | Summaries of threads, docs, logs, and meetings that keep the facts. |
+| write-report | Status updates, incident reports, and findings for a decision-maker. |
 | write-handoff | Handoff notes so work continues in a fresh session. |
 | write-longform | A staged long-form mission: collect raw material, then build the article. |
 | write-glossary | Build or clean a glossary, one term per concept. |
+| write-ste | Enforce Simplified Technical English on any text, violations named by rule. |
 
-## See the difference
-
-Every skill states what it changes. Three samples here. The full gallery of all fifteen is in `docs/examples.md`. The pairs are hand-written examples of the rules, not recorded sessions.
-
-write-core, a chat answer:
-
-```text
-Before: "Sure! I'd be happy to help. In order to boost your productivity,
-this robust tool leverages cutting-edge caching."
-After:  "The tool caches your queries. A repeat query answers in 12 ms."
-```
-
-write-pr, a PR body:
+## Proof
 
-```text
-Before: "This PR makes several improvements to the authentication system
-and cleans up a number of related issues."
-After:  "Summary: reject expired session tokens at login. Evidence: the
-reset test fails on main, passes here. Risk: two-way door, login only."
-```
+We ran all twenty-two skills in a controlled experiment. Each skill wrote one task with and without its own rules.
 
-write-jira, a story:
+| Verdict | Count |
+|---|---|
+| Clear pass | 13 |
+| Thin pass | 9 |
+| Fail | 0 |
 
-```text
-Before: "BE-1 Backend table (3)   BE-2 Upload endpoint (5)   WEB-1 Button (5)"
-After:  "One vertical story: POST /tasks/{id}/attachments saves the file,
-the web view lists it. Points: 5. Reason: one table, one endpoint,
-one screen in a single slice."
-```
+Read the method, the raw pairs, and the verdicts in [docs/EXPERIMENT.md](docs/EXPERIMENT.md).
 
-## Local rules
+## Your rules win
 
 Every skill reads your local rule files first: `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and `GLOSSARY.md`. Your glossary terms and repo conventions beat the skill defaults. The skills never edit those files.
 
 ## Install
 
-Install every skill from this repository:
+The skills CLI detects your agent and installs into the right folder:
 
 ```
 npx skills add adhamhaithameid/write-skills
@@ -67,23 +137,36 @@ npx skills add adhamhaithameid/write-skills
 Install one skill:
 
 ```
-npx skills add adhamhaithameid/write-skills --skill write-core
+npx skills add adhamhaithameid/write-skills --skill write-better
 ```
 
-Install the npm package, then copy a skill folder into the skills folder of your agent, for example `~/.claude/skills/`:
+Install the npm package and copy a skill folder into your agent's skills folder:
 
 ```
 npm install write-skills
 ```
 
-Or copy a folder from `skills/` by hand. Each skill folder holds everything the skill uses.
+| Agent | Skills folder |
+|---|---|
+| Claude Code | `~/.claude/skills/` |
+| Codex | `~/.agents/skills/` |
+| Any other agent | your agent's skills folder |
 
-No skill needs another skill.
+Or copy a folder from `skills/` by hand. Each skill folder holds everything the skill uses. No skill needs another skill.
 
 ## Output language
 
 Every skill writes its prose output in ASD-STE100 Simplified Technical English. Each skill carries its own copy of the rules in `references/ste.md`.
 
+## Docs
+
+- [docs/BLOCKS.md](docs/BLOCKS.md): the manifest and the set cap.
+- [docs/examples.md](docs/examples.md): the before-and-after gallery.
+- [docs/EXPERIMENT.md](docs/EXPERIMENT.md): the controlled before-and-after experiment.
+- [docs/STATE.md](docs/STATE.md): what the set is, skill by skill.
+- [docs/AUDIT.md](docs/AUDIT.md): the 24-check rubric scores.
+- [docs/EVALS.md](docs/EVALS.md): the behavior evidence.
+
 ## Check the repo
 
 Run these commands from the repo root:

package/THIRD_PARTY_NOTICES.md

@@ -6,7 +6,7 @@ This collection derives from the projects below. Each entry states the license a
 
 - mattpocock/skills (MIT). The agent-document reference and the three writing workflow stages (fragments, shape, beats) informed the agent mode of write-docs and the stages of write-longform. The vertical-slice ticket pattern informed write-jira. The text in this collection was rewritten and condensed. https://github.com/mattpocock/skills
 - humanlayer/skills, the show-me skill by Dex Horthy (credited in that skill). Its PR template idea, summary plus evidence plus merge danger, informed write-pr. The text in this collection was rewritten. https://github.com/humanlayer/skills
-- JuliusBrussee/caveman (MIT; the repository also ships an Apache-2.0 license file, and its plugin manifest declares MIT). The brief-voice rules in write-core and write-compact were written fresh for this collection. No text from that repository was copied. Named to credit the idea. https://github.com/JuliusBrussee/caveman
+- JuliusBrussee/caveman (MIT; the repository also ships an Apache-2.0 license file, and its plugin manifest declares MIT). The brief-voice rules in write-better and write-compact were written fresh for this collection. No text from that repository was copied. Named to credit the idea. https://github.com/JuliusBrussee/caveman
 - Hakku/finnish-humanizer (MIT). Its pattern-catalog method was reviewed during design. No text from it appears here. https://github.com/Hakku/finnish-humanizer
 
 ## Origin unknown
@@ -19,6 +19,13 @@ This collection derives from the projects below. Each entry states the license a
 - Diataxis framework by Daniele Procida. https://diataxis.org/. The four mode names are used under the framework.
 - Google developer documentation style guide. https://developers.google.com/style. The sentence rules in this collection are our own summary.
 
+## Ideas credited
+
+- Nate Berkopec, the TLDR-at-end-of-turn pattern from a public post of 26 October 2026. The rule text in write-tldr is our own. https://x.com/nateberkopec/status/2114819619513135180
+- The NYU and UT Austin study of reader-slowing patterns in model text, reported by The Decoder in October 2026. The seven pattern names and examples in reader-load.md are our own wording. https://the-decoder.com/researchers-find-six-patterns-that-make-ai-text-so-exhausting-to-read
+- Michael Nygard, the architecture decision record format used by write-adr. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+- superpowers:writing-plans, reviewed during the design of write-plan. No text copied. https://github.com/obra/superpowers
+
 ## Prior art
 
 - danyuchn/asd-ste100-skill. STE as an agent rule file. https://github.com/danyuchn/asd-ste100-skill

package/docs/AUDIT.md

@@ -6,7 +6,7 @@ Rubric: the 24-check skill checklist. Each check scores 0, 1, or 2. Weighted tot
 
 | Skill | Score | Percent | Grade |
 |---|---|---|---|
-| write-core | 58 | 81 percent | B |
+| write-better | 58 | 81 percent | B |
 | write-compact | 63 | 88 percent | B |
 | write-docs | 61 | 85 percent | B |
 | write-pr | 63 | 88 percent | B |
@@ -25,10 +25,10 @@ Rubric: the 24-check skill checklist. Each check scores 0, 1, or 2. Weighted tot
 
 ## Findings fixed in this audit
 
-1. Four skills used terms that only write-core defines: "floor rules" in write-compact, "reader level" in write-longform, and "level 2" in write-pr. All reworded. No skill now depends on the vocabulary of another.
+1. Four skills used terms that only write-better defines: "floor rules" in write-compact, "reader level" in write-longform, and "level 2" in write-pr. All reworded. No skill now depends on the vocabulary of another.
 2. Jargon before definition: "one-way door" in write-pr and "pile file" in write-longform. Both defined at first use, or reworded.
 3. write-docs claimed release notes while the manifest held them back. write-release now owns them, and the write-docs description dropped the claim.
-4. write-core claimed status updates and bug reports. write-report and write-issue own them now, so the three descriptions no longer collide.
+4. write-better claimed status updates and bug reports. write-report and write-issue own them now, so the three descriptions no longer collide.
 5. Four skills had no example. Every skill now carries one, and docs/examples.md holds the gallery.
 
 ## Weakest checks, set wide
@@ -42,7 +42,7 @@ Rubric: the 24-check skill checklist. Each check scores 0, 1, or 2. Weighted tot
 
 1. Run the eval cases for the seven new skills and the unrun core and longform cases.
 2. Add three should-not-fire prompts per skill to the routing test.
-3. Sharpen step endings into checkable criteria, starting with write-core and write-docs.
+3. Sharpen step endings into checkable criteria, starting with write-better and write-docs.
 4. Cap the set at fifteen until the trigger test proves no collisions.
 
 ## Method note

package/docs/BLOCKS.md

@@ -1,13 +1,18 @@
 # Block manifest
 
+The mission of this set: the reading experience must never feel like hell.
+
 One row for each block in this set. Change this file first when the set changes. The rule register in `docs/RULES.md` stays the authoring source for every rule a block embeds.
 
 ## The set
 
 | Block | Role | Activation |
 |---|---|---|
-| write-core | General prose floor: reader levels, depth, sentence rules, AI patterns. | Auto, on any prose task. |
-| write-compact | Brief replies on request, or rebuild a reply that did not land. | Auto, or "brief mode". |
+| write-better | General prose floor: reader levels, depth, sentence rules, AI patterns, reader load. | Auto, on any prose task. |
+| write-compact | The whole reply stays short. | Auto, or "brief mode". |
+| write-tldr | A short block at the end of a long answer: TLDR plus Found. | Auto, past 30 lines or on request. |
+| write-again | Rewrite the last output, explain again, or refresh a stale doc. | Auto, on "again" or "wait what". |
+| help-write | Read the conversation, name the skill that owns the deliverable. | On request, or when the type is unclear. |
 | write-docs | Documents for humans, and documents an agent reads. | Auto, on document tasks. |
 | write-pr | PR title and body from the change and the evidence. | Auto, on PR text. |
 | write-commit | Commit message from the staged diff and the history. | Auto, on commit text. |
@@ -21,6 +26,10 @@ One row for each block in this set. Change this file first when the set changes.
 | write-handoff | Handoff notes for a fresh session. | Auto, on handoff requests. |
 | write-longform | Staged long-form mission under one shared brief. | Explicit request only. |
 | write-glossary | Build or clean a glossary, one term per concept. | Auto, on glossary work. |
+| write-plan | A plan before work starts: goal, approaches, steps, risks. | Auto, on plan requests. |
+| write-adr | Architecture decision records in the Nygard shape. | Auto, on decision records. |
+| write-prd | Product requirements: problem, goals, requirements, metrics. | Auto, on PRD requests. |
+| write-ste | Enforce STE on any text, violations named by rule. | Auto, on "ste" requests. |
 
 ## Design rules
 
@@ -44,4 +53,4 @@ The upstream projects and their licenses are listed in `THIRD_PARTY_NOTICES.md`.
 
 ## Set size
 
-Fifteen descriptions load in every session. Watch trigger overlap before adding a sixteenth. The routing test in `docs/EVALS.md` is the regression net.
+Twenty-two descriptions load in every session. The negative-trigger routing test in `docs/ROUTING-TEST.md` is the regression net. It is pending for the 22-skill set. Run it before adding a twenty-third.

package/docs/EVALS.md

@@ -21,7 +21,7 @@ Date: 24 October 2026. Method: one eval case per skill, run twice in fresh agent
 
 ## Reading
 
-- Every block now carries eval cases in its `evals/` folder. Cases for write-core and write-longform are written but not run.
+- Every block now carries eval cases in its `evals/` folder. Cases for write-better and write-longform are written but not run.
 - The PR, Jira, and commit blocks change behavior in the intended direction. The commit value sits in the process rules, proven by the live-repo test: read the history first, let the repo convention win.
 - The compact block earns a partial pass. The docs and comments blocks show thin separation on one case each. The base model is already close, and the skill adds placement and ordering discipline.
 - Trigger routing is clean: 16 of 16 in two samples. This test shows the descriptions as written to a host. A real host injects them differently, so in-host firing stays unverified.
@@ -30,3 +30,26 @@ Date: 24 October 2026. Method: one eval case per skill, run twice in fresh agent
 ## Run more
 
 The cases live in `skills/<name>/evals/evals.json`. Run a case with two fresh agents: one gets the bare prompt, one gets the prompt with the skill text. Grade both outputs against the assertions.
+
+## 29 October 2026, 0.4.0
+
+- The negative-trigger routing test for the 22-skill set is pending. The provider refused the subagent dispatch three times. The fixture, with expected answers, is saved in docs/ROUTING-TEST.md. Run it before adding a twenty-third skill and after any description change.
+- Eval cases are written for all seven new skills. None has run yet.
+- Name check on skills.sh: write-tldr, write-again, help-write, write-adr, write-prd, write-ste, and write-better are free. write-plan exists under another owner and is kept under the owner-namespacing policy.
+
+## 30 to 31 October 2026, the full experiment
+
+All 22 skills ran with and without their rules on the subagent channel, prompt only, no tools. 13 clear passes, 9 thin passes, 0 failures. OpenCode on beam-free confirmed in-host firing and the local-rules step, but its control arms auto-fired the skills, so that channel is qualitative only. Full pairs and verdicts: docs/EXPERIMENT.md. beam-free is unfit for graded runs; it duplicated answers across turns.
+
+## 7 November 2026, the 22-skill routing test
+
+Method: the fixture in docs/ROUTING-TEST.md, two runs per part, four fresh subagents, prompt only. The prompts went verbatim.
+
+| Part | Run | Verdicts | Result |
+|---|---|---|---|
+| A, should fire | 1 | 9 of 10 | One over-fire: task 10, "Which skill should I use to describe this endpoint to the team?" fired write-docs; expected help-write. |
+| A, should fire | 2 | 9 of 10 | One over-fire: task 5, "Run the test suite and report failures", fired write-report; expected none. |
+| B, should not fire | 1 | 10 of 10 | No misfires. |
+| B, should not fire | 2 | 10 of 10 | No misfires. |
+
+Total: 38 of 40 verdicts correct. The negative-trigger test is green in both runs, so the gate for a twenty-third skill is open. The two part-A misses are over-fires, not missed triggers: no skill failed to fire when it should. Both sit near a real boundary. Task 10 is a meta-question about skill choice; help-write owns it, and write-docs guessed. Task 5 asks for a report of failures; write-report read "report" in the prompt. No description change is planned, so no rerun is required.