feat(skills): add shared Cursor agent skills

.cursor/skills/README.md

@@ -0,0 +1,122 @@
+# Docs skills
+
+Cursor [Agent Skills](https://docs.cursor.com/agent/skills) that enforce our documentation standards on every repo that uses this template. The skills are the source of truth for **what good docs look like at Tether** and are intended to be shared, versioned, and updated centrally from `docs-template`.
+
+## What's in here
+
+| Skill | Purpose |
+|---|---|
+| [`diataxis/`](./diataxis/) | Classifies each MDX page as tutorial, how-to, reference, or explanation, enforces the structure and voice of each, and aligns with the `docType` enum in `@tetherto/docs-seo-schema`. |
+| [`google-tech-writing/`](./google-tech-writing/) | Applies Google's developer documentation style guide: active voice, second person, present tense, sentence-case headings, defined acronyms, banned filler ("easy", "simple", "just"), tiered severity for review. |
+| [`docs-frontmatter/`](./docs-frontmatter/) | Enforces the SEO frontmatter contract from `@tetherto/docs-seo-schema`: required `description`, recommended `docType` matching directory, and optional `ogImage`, `noIndex`, and `lastModified`. |
+| [`docs-review/`](./docs-review/) | Orchestrates the three skills above against a file list or PR diff and emits a single tiered report (must-fix / consider / nit). |
+
+All four are **project-level** skills — placed under `.cursor/skills/` so Cursor picks them up automatically for anyone working in the repo.
+
+## How Cursor discovers them
+
+Cursor reads project skills from `.cursor/skills/` in the workspace root. No installation step is required for users of a repo that contains this directory; the skills are visible to the agent the moment the repo is opened.
+
+If you want these skills available across every project on your machine (in addition to the project-level pickup above), symlink them into `~/.cursor/skills/`. Run from the root of a checked-out copy of `docs-template` so `$PWD` resolves to the right location:
+
+```bash
+# from the docs-template repo root
+ln -s "$PWD/.cursor/skills/diataxis"            ~/.cursor/skills/diataxis
+ln -s "$PWD/.cursor/skills/google-tech-writing" ~/.cursor/skills/google-tech-writing
+ln -s "$PWD/.cursor/skills/docs-frontmatter"    ~/.cursor/skills/docs-frontmatter
+ln -s "$PWD/.cursor/skills/docs-review"         ~/.cursor/skills/docs-review
+```
+
+Project-level skills in any repo's `.cursor/skills/` take precedence over personal skills with the same name, so the symlinks are a safety net for repos that have not yet adopted the template.
+
+## Sharing across the org
+
+`docs-template` is the single source of truth. Consumer repos pick up skills via one of three flows. Pick the one that matches your team's update cadence.
+
+### Option A — One-shot copy (`tiged` / `degit`)
+
+Best for: new repos, occasional manual re-syncs, no need to track upstream changes.
+
+```bash
+# from the consumer repo root
+npx --package=tiged@2 -- tiged tetherto/docs-template/.cursor/skills .cursor/skills --force
+```
+
+Pin a tag or commit:
+
+```bash
+npx --package=tiged@2 -- tiged tetherto/docs-template/.cursor/skills#v1.2.0 .cursor/skills --force
+```
+
+### Option B — `npm run sync-skills` (recommended)
+
+Best for: repos that want a documented, reproducible sync command in their own `package.json`.
+
+The template ships [`scripts/sync-skills.mjs`](../../scripts/sync-skills.mjs) and an `npm run sync-skills` entry. Copy both into your consumer repo (or call the script via `tiged` once and commit it). Then:
+
+```bash
+# default: pulls latest main from tetherto/docs-template
+npm run sync-skills
+
+# pin to a tag
+npm run sync-skills -- --ref=v1.2.0
+
+# point at a fork
+npm run sync-skills -- --repo=myorg/my-docs-template --ref=main
+
+# preview without writing
+npm run sync-skills -- --dry-run
+```
+
+Environment variables also work (`DOCS_SKILLS_REPO`, `DOCS_SKILLS_REF`). The script refuses to run inside `docs-template` itself, so it cannot clobber the source of truth.
+
+### Option C — `git subtree` (history-preserving)
+
+Best for: teams that want upstream history merged into their repo and clean conflict resolution when both sides edit a skill.
+
+First-time set-up in the consumer repo:
+
+```bash
+git remote add docs-template https://github.com/tetherto/docs-template.git
+git subtree add --prefix=.cursor/skills docs-template main --squash
+```
+
+Subsequent updates:
+
+```bash
+git fetch docs-template
+git subtree pull --prefix=.cursor/skills docs-template main --squash
+```
+
+Send local improvements back upstream:
+
+```bash
+git subtree push --prefix=.cursor/skills docs-template feature/<your-improvement>
+# then open a PR in docs-template
+```
+
+## Update workflow (org-wide)
+
+1. Open a PR against [`tetherto/docs-template`](https://github.com/tetherto/docs-template) modifying the relevant skill under `.cursor/skills/`.
+2. Tag a release (`v1.x.y`) when the change is ready to roll out.
+3. Consumer repos run their sync command (Option A / B) or `git subtree pull` (Option C), pinning to the new tag if they want stable rollout.
+4. To detect drift in CI, run `npm run sync-skills` followed by `git diff --exit-code .cursor/skills/`. The diff returns non-zero when local skills differ from the upstream ref, which fails the build (optional, opinionated). `--dry-run` only logs the planned action; it does not perform a comparison on its own.
+
+## Authoring conventions for skills in this directory
+
+Anyone editing skills here should keep them tight and predictable so the agent can rely on them across many repos:
+
+- **One concern per skill.** Cross-link instead of duplicating.
+- **Top-level `SKILL.md` under 500 lines.** Push depth into sibling `.md` files (progressive disclosure).
+- **Third-person, specific descriptions** in YAML frontmatter — the agent reads only the description until the skill is invoked.
+- **Tiered severity** (must-fix / consider / nit) wherever the skill produces review output, so `docs-review` can aggregate cleanly.
+- **No time-sensitive content** ("by August 2025…"); use a "deprecated patterns" section if needed.
+- **Match the schema and directory layout of this template.** Mode-to-directory tables in `diataxis/SKILL.md` and the `docType` enum in `@tetherto/docs-seo-schema` must stay aligned.
+
+## Reference
+
+- [Cursor Agent Skills documentation](https://docs.cursor.com/agent/skills)
+- [Diataxis framework](https://diataxis.fr)
+- [Google developer documentation style guide](https://developers.google.com/style)
+- [Google technical writing courses](https://developers.google.com/tech-writing)
+- Schema source: [`packages/docs-seo-schema/src/index.ts`](../../packages/docs-seo-schema/src/index.ts)

.cursor/skills/diataxis/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: diataxis
+description: >-
+  Classifies documentation pages into the four Diataxis modes (tutorial,
+  how-to, reference, explanation) and enforces the structure, voice, and
+  scope of each. Use when authoring, reviewing, or refactoring docs in
+  content/docs/**, when the user mentions Diataxis, tutorials, how-to guides,
+  reference, or explanation, or when frontmatter docType is set or missing.
+---
+
+# Diataxis
+
+Diataxis is a documentation framework that splits docs into four modes based on what the reader needs *right now*. Mixing two modes in one page is the most common documentation defect this skill exists to prevent.
+
+| Mode | Reader's need | Reader's question | Voice |
+|---|---|---|---|
+| Tutorial | Learning by doing | "Teach me." | Confident, hand-holding, present tense |
+| How-to guide | Solving a specific task | "Show me how." | Direct, imperative, goal-focused |
+| Reference | Looking up facts | "Tell me." | Austere, neutral, complete |
+| Explanation | Understanding context | "Help me think about this." | Discursive, analytical |
+
+Source: [diataxis.fr](https://diataxis.fr).
+
+## Step 1 — Classify the page
+
+Before writing or reviewing, decide which mode the page is in. Use this decision tree, **in order**:
+
+1. Is the reader expected to **follow concrete steps and finish with a working artifact they did not have before**?
+   - **Yes, and they are new to the system** → **Tutorial**
+   - **Yes, but they already know the system and want to accomplish a specific goal** → **How-to**
+2. Is the reader looking up **facts about an API, schema, CLI, config, or behaviour** with no narrative arc?
+   → **Reference**
+3. Is the reader trying to **understand why something works the way it does**, the trade-offs, or the historical context, with no concrete steps required?
+   → **Explanation**
+
+If two answers feel correct, the page is doing two jobs and must be split.
+
+### Mapping to this template's directory and frontmatter
+
+| Diataxis mode | `content/docs/` directory | `docType` value (from `@tetherto/docs-seo-schema`) |
+|---|---|---|
+| Tutorial | `tutorials/` | `tutorial` |
+| How-to guide | `how-tos/` | `how-to` |
+| Reference | `references/` | `reference` |
+| Explanation | `explanation/` | `explanation` |
+| Onboarding orientation | `getting-started/` | `getting-started` |
+| FAQ | `faqs/` | `faq` |
+| Generic landing/index | top-level `index.mdx` | `page` |
+
+`getting-started`, `faq`, and `page` are template-specific helpers, not Diataxis modes. Treat them as follows:
+
+- `getting-started` is a **tutorial** in spirit. Apply tutorial rules.
+- `faq` answers concrete questions. Apply how-to rules per answer.
+- `page` (landing pages) should orient readers toward the four real modes; do not pack content here.
+
+## Step 2 — Apply the mode-specific rules
+
+Read only the file for the mode you are working on:
+
+- Tutorial → [tutorial.md](tutorial.md)
+- How-to guide → [how-to.md](how-to.md)
+- Reference → [reference.md](reference.md)
+- Explanation → [explanation.md](explanation.md)
+
+If you are reviewing several pages in one session, read each mode file once at the start and keep it in context.
+
+## Step 3 — Run the universal Diataxis checklist
+
+Apply this to every page regardless of mode:
+
+- [ ] The page has exactly **one** Diataxis mode. No tutorial-style narrative inside reference. No how-to checklist inside explanation. No conceptual essay inside a tutorial.
+- [ ] The directory under `content/docs/` matches the mode (see table above).
+- [ ] `docType` in frontmatter matches the directory and the actual content.
+- [ ] The opening paragraph signals the mode to the reader (for example, a tutorial opens with "In this tutorial you will…", a how-to opens with "This guide shows you how to…", a reference opens with a one-line factual summary, an explanation opens with the question it answers).
+- [ ] Cross-links point to the right mode for follow-up: tutorials link to how-tos and reference, how-tos link to reference, reference links to explanation, explanation links to tutorials and how-tos. Avoid linking like-to-like in long chains.
+- [ ] Content from another mode that crept in is either removed, inlined as a single short sentence, or extracted to a sibling page in the correct directory and linked.
+
+## Step 4 — Report findings
+
+When reviewing, output findings using the [tiered severity](../docs-review/SKILL.md) the rest of the suite uses:
+
+- **must-fix**: page is in the wrong directory or `docType`, or mixes two modes in a way that confuses the reader.
+- **consider**: a section belongs in another mode and should be split out, or cross-links go to the wrong mode.
+- **nit**: opening paragraph does not signal the mode, headings do not match the mode's voice.
+
+## Anti-patterns
+
+- A "tutorial" that is really a feature tour — readers do not finish with a working artifact. Reclassify as explanation or split.
+- A "how-to" with motivation, history, and trade-offs woven through — move that prose into a sibling explanation.
+- A "reference" page that teaches — move teaching content into a tutorial; keep reference dry.
+- An "explanation" with copy-pasteable steps — extract the steps into a how-to.
+- Calling everything "Getting started" — only the **first** orientation page is `getting-started`. Subsequent learning material is tutorial; subsequent task material is how-to.
+
+## When the user asks you to write a new page
+
+1. Ask (or infer) the Diataxis mode using Step 1.
+2. Place the file in the directory from Step 1's table.
+3. Set `docType` in frontmatter (see [`docs-frontmatter`](../docs-frontmatter/SKILL.md)).
+4. Open the relevant mode file and follow its template.
+5. Run the universal checklist before finishing.
+
+## When the user asks you to review or refactor docs
+
+1. Classify each page (Step 1).
+2. For each page, run the mode-specific rules and the universal checklist.
+3. Group findings by file and severity.
+4. Hand off to [`docs-review`](../docs-review/SKILL.md) if the user asked for a full audit (Diataxis + Google style + frontmatter).

.cursor/skills/diataxis/explanation.md

@@ -0,0 +1,68 @@
+# Explanation mode
+
+Explanation is **understanding**. The reader steps back from the keyboard and wants to know *why* the system is the way it is — the model, the trade-offs, the history, the alternatives that were rejected. The reader does not need to act after reading.
+
+## Rules
+
+1. **The page answers a question, not a task.** Good titles are nouns and questions: "How replication works", "Why Pear chose hypercore", "Trade-offs of P2P discovery". Avoid "How to…" titles in this mode.
+2. **Open with the question and the audience.** "This page explains *why* we use X. Read it if you are deciding whether to adopt X or wondering about its limits."
+3. **Discursive prose is allowed and welcome.** Explanation is the only Diataxis mode where long-form paragraphs and analogies are appropriate.
+4. **Discuss alternatives and trade-offs.** Naming the alternatives the team rejected is often the most useful part of an explanation page.
+5. **Do not include step-by-step instructions.** If the reader asks "how do I do this?" after reading, link them to a how-to.
+6. **Do not duplicate reference content.** Do not list every parameter. Describe the *shape* of the API and link to reference for facts.
+7. **Cite sources where useful** — RFCs, papers, prior art, internal design docs. Make the reasoning checkable.
+8. **End with "Where to go next"** that points to a tutorial, how-to, or reference based on what the reader will likely do next.
+
+## Template
+
+```mdx
+---
+title: <Question or noun phrase>
+description: <One sentence: what this page helps the reader understand.>
+docType: explanation
+---
+
+<!-- file path: content/docs/explanation/<slug>.mdx -->
+
+# <Title>
+
+This page explains <topic>. Read it if you are <audience signal>.
+
+## The short version
+
+<Two- or three-sentence summary of the answer. Readers should be able to stop here if they only need the headline.>
+
+## <Section: the model>
+
+<Discursive prose explaining the conceptual model.>
+
+## <Section: trade-offs and alternatives>
+
+<What we picked, what we did not, and why.>
+
+## <Section: limits and open questions>
+
+<Honest accounting of where the design is incomplete.>
+
+## Where to go next
+
+- To try it, follow [<tutorial>](/tutorials/<slug>).
+- To do <related task>, see [<how-to>](/how-tos/<slug>).
+- For exhaustive details, see [<reference>](/references/<slug>).
+```
+
+## Common defects
+
+- **Sales pitch.** Explanation should be honest, not promotional. Name the trade-offs.
+- **How-to disguise.** If the page contains numbered steps the reader is expected to run, move them to a how-to.
+- **Reference dump.** If the page lists every option, move that to reference and keep only the conceptual map here.
+- **Unbounded scope.** "About X" pages tend to grow into everything. Split when the page exceeds ~1500 words or covers more than one question.
+- **No links out.** Explanation that does not point to actions leaves the reader stranded.
+
+## Examples of good and bad opens
+
+**Good:** "This page explains why Pear uses Hypercore for storage rather than a traditional database. Read it if you are evaluating Pear or wondering about durability guarantees."
+
+**Bad:** "Pear is awesome and here is everything about it." (No question, no audience, no trade-offs.)
+
+**Bad:** "How replication works: 1. Open a feed. 2. Append blocks. 3. Sync." (Steps belong in a how-to. Use prose to describe the model.)

.cursor/skills/diataxis/how-to.md

@@ -0,0 +1,89 @@
+# How-to guide mode
+
+A how-to guide is a **recipe** for solving a specific real-world problem. The reader already knows the basics — they have a goal and need the shortest reliable path to it.
+
+## Rules
+
+1. **Title states the goal as a task.** "How to <verb> <object>." If you cannot phrase the title that way, the page is probably reference or explanation.
+2. **Open with one sentence stating who the guide is for and what they will accomplish.** "This guide shows you how to <X> when you already have <Y>."
+3. **Assume working knowledge.** Do not re-teach the basics. Link to a tutorial if a foundation is needed.
+4. **Steps must be ordered, numbered, and minimal.** No motivational interludes between steps.
+5. **State preconditions explicitly** (versions, permissions, files, environment variables) before step 1.
+6. **Use second person, imperative, present tense.** Same voice as tutorials.
+7. **Cover the realistic variations** the reader is likely to hit (one OS detour, one auth variant), but resist branching into a tree.
+8. **End with verification** — how the reader confirms they succeeded — and links to related how-tos and reference.
+9. **Do not explain *why*.** Link to an explanation page if the design choice is non-obvious.
+
+## Template
+
+````mdx
+---
+title: How to <verb> <object>
+description: <One sentence: the goal and the precondition.>
+docType: how-to
+---
+
+# How to <verb> <object>
+
+This guide shows you how to <goal> when you already have <precondition>.
+
+## Before you begin
+
+You need:
+
+- <Tool / version>
+- <Permission / access>
+- <Existing artifact, if any>
+
+## Steps
+
+1. <Imperative verb>. <One line of context if essential.>
+
+   ```bash
+   <command>
+   ```
+
+2. <Imperative verb>.
+
+   ```bash
+   <command>
+   ```
+
+3. <Imperative verb>.
+
+## Verify
+
+Run:
+
+```bash
+<verification command>
+```
+
+You should see <expected outcome>.
+
+## Troubleshooting
+
+- **<Symptom>.** <Cause and fix in one sentence.>
+- **<Symptom>.** <Cause and fix in one sentence.>
+
+## Related
+
+- [How to <related task>](/how-tos/<slug>)
+- [<Reference page>](/references/<slug>)
+````
+
+## Common defects
+
+- **Tutorial drift.** A how-to that opens with "In this tutorial…" or includes long context. Tighten the open and cut context.
+- **Reference drift.** A how-to that lists every flag of a command. Move flags to reference; keep only the ones used in the steps.
+- **Explanation drift.** A how-to that justifies each design decision in prose. Cut or link out.
+- **Bag of tips.** A page titled "How to use X" is too broad. Split into specific goals: "How to migrate X", "How to back up X", "How to monitor X".
+- **No verification step.** The reader cannot tell if it worked. Always include a confirmation.
+
+## Examples of good and bad opens
+
+**Good:** "This guide shows you how to publish a Pear application to a private hyperdrive when you already have a working app and a hyperdrive key."
+
+**Bad:** "Publishing Pear apps is an important part of the workflow. This guide will help you understand and execute the publishing process." (Padding, no goal.)
+
+**Bad:** "How to use Pear" (Too broad. Split.)