writing-skills 0.1.1 → 0.3.1

package/README.md

@@ -1,77 +1,86 @@
 <p align="center">
-  <img src="logo.svg" alt="Writing Skills Logo" width="120" />
+  <img src="logo.svg" alt="writing-skills logo" width="96" />
 </p>
 
-# Writing Skills 🖋️
+# writing-skills
+
+**14 writing-style skills for AI agents: 7 measurable frameworks, 7 character voices.**
+Plain `SKILL.md` files — no code, no server. Works in any agent that reads skills
+(Claude Code, opencode, Codex, Cursor, Kiro, Gemini).
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PyPI](https://img.shields.io/pypi/v/writing-skills)](https://pypi.org/project/writing-skills/)
 [![npm](https://img.shields.io/npm/v/writing-skills)](https://www.npmjs.com/package/writing-skills)
+[![PyPI](https://img.shields.io/pypi/v/writing-skills)](https://pypi.org/project/writing-skills/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Procedural writing-style skills for AI agents — official frameworks, not vibes.**
+## Install
 
-Ready-made `SKILL.md` packages: plain language, business writing, corporate
-communication, GOV.UK, AP style, STE-100, dev docs — each with numbered mechanics
-and a **verifiable checklist** the agent must pass. Compatible with any agent that
-reads SKILL.md (opencode, Claude Code, Codex, Kiro, Gemini).
+```bash
+npx skills add writing-skills
+```
 
-## Skills
+One command, every agent on your machine.
 
-### Frameworks
+<details>
+<summary>Other install methods</summary>
 
-| Skill | What it enforces |
+| Harness | Command |
 | :--- | :--- |
-| `plain-language` | Plain Writing Act clarity. Sentences ≤25 words, passive ≤10%, jargon ban list. |
-| `business-writing` | Executive comms. BLUF in the first line, explicit ask + deadline, buzzword ban list. |
-| `corporate-communication` | Company announcements. News first, reader impact explicit, zero euphemism. |
-| `gov-uk-style` | Public-sector readability. Keyword-first headings, ≤25-word sentences, ≤5-sentence paragraphs. |
-| `asd-ste100` | Safety-critical technical prose. One instruction per sentence, controlled vocabulary, no idioms. |
-| `google-dev-docs` | Developer documentation. Active voice, present tense, verb-first headings, runnable examples. |
-| `journalism-ap` | Factual reporting. AP attribution and number rules, zero editorializing. |
+| Claude Code plugin | `/plugin marketplace add surendranb/writing-skills` then `/plugin install writing-skills@writing-skills` |
+| Codex ≥ 0.147 / Kiro | `git clone https://github.com/surendranb/writing-skills.git` — `plugin.json` is auto-discovered |
+| npm | `npm install writing-skills` |
+| Python | `uv add writing-skills` or `pip install writing-skills` |
 
-### Voices
+</details>
 
-`ted-lasso` · `jack-sparrow` · `shrek` · `yoda` · `winnie-the-pooh` · `paddington` · `bob-ross`
+## Use
 
-## Install
+Ask for the style. The skill loads itself.
 
-```bash
-npx skills add writing-skills      # installs into every detected agent (Claude Code, opencode, Codex, ...)
-npm install writing-skills         # or pip/uv: uv add writing-skills
-```
+> "rewrite this in plain language" · "make this a BLUF business update" ·
+> "press release in AP style" · "say it like Yoda"
 
-`writing-skills` is also an Agent Plugins 1.0.0 package — Claude Code, Codex ≥ 0.147
-and Kiro discover `plugin.json` when you point them at the repo:
+Every skill ends with a `Verify` checklist the agent must pass before it delivers.
 
-```bash
-git clone https://github.com/surendranb/writing-skills.git
-```
-
-## Use
+## The skills
 
-Ask for a style and the skill loads automatically:
+### Frameworks — real standards, enforced
 
-> "rewrite this in plain language"
-> "make this a BLUF business update"
-> "write the press release in AP style"
-> "say it like Ted Lasso"
+| Skill | Enforces |
+| :--- | :--- |
+| `plain-language` | Plain Writing Act. Sentences ≤25 words, passive ≤10%, jargon ban list. |
+| `business-writing` | BLUF first line, explicit ask + deadline, buzzword ban list. |
+| `corporate-communication` | News first, reader impact named, zero euphemism. |
+| `gov-uk-style` | GOV.UK guide. Keyword-first headings, ≤5-sentence paragraphs. |
+| `asd-ste100` | Simplified Technical English. One instruction per sentence, no idioms. |
+| `google-dev-docs` | Google style. Active voice, present tense, verb-first headings. |
+| `journalism-ap` | AP Stylebook. Attribution, number rules, zero editorializing. |
 
-Every framework skill ends with a `Verify` checklist (sentence caps, passive-voice
-scans, ban lists, readability targets) the agent must pass before delivering.
+### Voices — characters, rate-limited against caricature
 
-## Contribute
+`ted-lasso` · `jack-sparrow` · `shrek` · `yoda` · `winnie-the-pooh` · `paddington` · `bob-ross`
 
-Add a skill as a folder under `skills/` with a `SKILL.md`:
+## MCP server — unlimited skills, live from GitHub
 
-- `name` in frontmatter matching the folder; trigger-rich `description` starting with "Use when"
-- `## The core rule`, `## Mechanics` (numbered, verifiable), `## Do not`, and at least two before/after `## Transform example`s
+```bash
+uvx writing-skills-mcp
+```
 
-Validate locally:
+The plugin ships 14 skills statically. The MCP server is the living registry
+on top: it discovers styles from the full catalog on GitHub (`search_styles`),
+returns any skill's full `SKILL.md` (`get_skill`), and installs it into a
+harness skills directory (`install_skill`). A new skill is just a commit —
+no package update, no re-install, at any scale.
 
 ```bash
-python3 scripts/check_skills.py    # requires PyYAML
+uvx --from writing-skills writing-skills-mcp
 ```
 
+## Contribute
+
+Copy [template/SKILL.md](template/SKILL.md), fill it, run
+`python3 scripts/validate_skills.py`. CI enforces the contract — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
-MIT — [Surendran B](https://github.com/surendranb). See [LICENSE](LICENSE).
+MIT — [Surendran B](https://github.com/surendranb)