feat(skills): add shared Cursor agent skills

[lucas-tortora]

Summary

Adds a .cursor/skills/ directory shipping four project-level Cursor agent skills that enforce Tether's documentation standards on any repo derived from this template, plus a sync script and a small content rename so the template's own docs follow the new Diataxis layout.

The four skills:

Skill	Purpose
diataxis	Classifies each MDX page as tutorial, how-to, reference, or explanation, enforces the structure and voice of each, and aligns with docType in @tetherto/docs-seo-schema.
google-tech-writing	Applies Google's developer documentation style guide (active voice, second person, present tense, sentence-case headings, banned filler, tiered review severity).
docs-frontmatter	Enforces the SEO frontmatter contract from @tetherto/docs-seo-schema: required description, recommended docType matching directory, and optional ogImage, noIndex, lastModified.
docs-review	Orchestrates the three skills above against a file list or PR diff and emits a single tiered report (must-fix / consider / nit).

Cursor reads project skills from .cursor/skills/ automatically — no install step. Three sync flows for consumer repos are documented in .cursor/skills/README.md: tiged, npm run sync-skills, or git subtree.

What's in the change

• Skills — .cursor/skills/{diataxis,google-tech-writing,docs-frontmatter,docs-review}/ (a SKILL.md per skill plus supporting .md files for progressive-disclosure depth content), plus .cursor/skills/README.md documenting the sync flows and authoring conventions.
• Sync script — scripts/sync-skills.mjs + npm run sync-skills. Uses spawnSync (no shell-quoting risks). Surfaces actionable errors on missing git binary, raw commit SHAs in --branch, and other failure paths. Refuses to run inside docs-template itself via a package-name + git-remote cross-check, so the source of truth cannot self-overwrite. Refuses to clobber a dirty .cursor/skills/ in a consumer repo unless --force is passed, so contributors do not lose local edits.
• Content rename — replace placeholder content/docs/about/about.mdx with a real Diataxis explanation page at content/docs/explanation/explanation.mdx ("Why DOCS is a template, not a SaaS"). Update content/docs/index.mdx, src/lib/custom-tree.ts, and the three sibling section landings to match. Drop the accent on "Diátaxis" → "Diataxis" across content/docs/** and the schema's warn message for consistency.
• Top-level README — new "Documentation skills" section with a skill table, plus a repository-layout bullet pointing at .cursor/skills/.
• package.json — sync-skills script added; lifecycle scripts grouped (dev, build family, postinstall, runtime, automation).

Design notes

• No schema bump required. An earlier iteration enforced description.max(200) in tetherSeoFrontmatterSchema. That was reverted to keep the schema package source byte-identical with the published @tetherto/docs-seo-schema@1.1.0, so the publish workflow's npm view <pkg>@<version> short-circuit stays correct and consumers do not need to coordinate. The 200-char guidance is now advisory in the docs-frontmatter skill.
• All skill files self-apply. Each SKILL.md follows the rules it enforces (active voice, sentence-case headings, no banned filler, parallel lists). Templates inside tutorial.md, how-to.md, reference.md, and docs-review/SKILL.md use 4-backtick outer fences to render correctly with their nested 3-backtick inner code blocks.
• No new runtime deps. scripts/sync-skills.mjs only imports Node built-ins (node:child_process, node:fs, node:os, node:path, node:process).

Test plan

• tsc --noEmit clean in packages/docs-seo-schema.
• node scripts/sync-skills.mjs --help lists --force and prints help cleanly.
• node scripts/sync-skills.mjs --dry-run inside docs-template exits 2 with the self-overwrite refusal message (validates the package-name + git-remote guard).
• All MDX description frontmatter values render as before; no Diátaxis left in the tree (grep returns 0 matches).
• All four SKILL.md files use Cursor's frontmatter format (name, description as a folded scalar with concrete trigger conditions).
• Code-fence rendering verified across tutorial.md, how-to.md, reference.md, and docs-review/SKILL.md: 4-backtick outer fences wrap the inner 3-backtick code samples, so each template renders intact.
• On-PR: npm run check-links and any existing PR-level CI.
• On-PR: visual check that GitHub-rendered anchors in the two READMEs (README.md, .cursor/skills/README.md) and the explanation page resolve correctly.

Rollout

1. Merge to main. Cursor immediately picks up the new skills for anyone working in this repo.
2. Tag a release (v1.x.y) when ready to roll out to consumer repos.
3. Consumer repos run npm run sync-skills -- --ref=v1.x.y (Option B) or git subtree pull (Option C) to pull in the new skills.
4. To detect drift in CI, a consumer can run npm run sync-skills followed by git diff --exit-code .cursor/skills/.

Reviewer guidance

Most of the diff is documentation. The non-doc surface is small and worth reviewing first:

• scripts/sync-skills.mjs (~200 lines, all new)
• package.json (script added + lifecycle reorder)
• src/lib/custom-tree.ts (sidebar rename only)
• packages/docs-seo-schema/src/index.ts (one-line accent change in a warn string; otherwise unchanged on this branch)

After that, the four SKILL.md files are the spec the agent reads at runtime; the supporting .md files (e.g. tutorial.md, examples.md, checklist.md) are progressive-disclosure depth that the agent only reads when working in the relevant mode.