chore(claude-md): prune CLAUDE.md per hygiene audit (companion to ppds#815)

.claude/skills/write-blog/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: write-blog
+description: Authoring blog posts in ppds-docs — first-person voice, technical narrative. Use when drafting a blog post or release recap.
+---
+
+# Write Blog
+
+Voice and structure for the blog. Different from `write-docs` — blog
+posts are personal, narrative, and opinionated.
+
+## When to Use
+
+- Writing a new blog post under `blog/`
+- Drafting a release recap or technical deep-dive
+- Reviewing a blog PR
+
+## Voice
+
+- **First person singular** ("I discovered...", "we ran into..." for
+  collaborative posts).
+- **Conversational but technical** — read like a smart colleague at a
+  whiteboard, not a marketing brochure.
+- **Show the struggle, not just the solution.** The interesting part is
+  what didn't work and why; the fix is usually one paragraph.
+- **Include real numbers.** "5x faster" is fine; "much faster" is not.
+  Cite the benchmark, the row count, the wall-clock seconds.
+
+## Structure
+
+A typical post:
+
+1. Hook — the question or problem that prompted the work, in 2–3
+   sentences.
+2. What you tried first — the wrong path, why it seemed right at the
+   time.
+3. The pivot — the insight that changed the approach.
+4. The solution — code, numbers, links to source.
+5. What's next — what this enables, what is still open.
+
+## What to Avoid
+
+- Marketing fluff ("revolutionary", "industry-leading"). Cut on sight.
+- Posts that are only the solution. The insight is what readers come for.
+- Screenshots and informative images without alt text. Write alt text
+  that describes what the user should perceive — the data shown, not
+  "screenshot of dashboard". Decorative images (banners, dividers) should
+  use an empty alt attribute (`alt=""`) per WCAG so screen readers skip
+  them.
+
+## Why This Lives in a Skill, Not CLAUDE.md
+
+Blog voice only matters when writing blog posts. Loading it every session
+would crowd out rules that always apply.

.claude/skills/write-docs/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: write-docs
+description: Authoring docs in ppds-docs — Diátaxis classification, voice, style. Use when writing or restructuring tutorials, guides, reference, or concept docs.
+---
+
+# Write Docs
+
+Conventions for the documentation site. Triggers when authoring or
+reorganizing prose under `docs/`.
+
+## When to Use
+
+- Writing a new doc page
+- Refactoring an existing page that does not fit cleanly in one Diátaxis bucket
+- Reviewing a PR that touches `docs/`
+
+## Diátaxis Classification
+
+Every doc fits exactly one of these buckets. If you cannot pick one, the
+doc needs to be split.
+
+| Type | Purpose | Voice |
+|------|---------|-------|
+| Tutorial | Learning-oriented, step-by-step | Hand-hold the reader through a complete experience |
+| Guide | Task-oriented, goal-focused | Show the most direct path to the user's goal |
+| Reference | Information-oriented, complete | Be exhaustive and predictable; no opinions |
+| Concept | Understanding-oriented, explains why | Explain the model and tradeoffs; no procedure |
+
+Mixing types in one page is the most common drift. A tutorial that becomes
+a reference table is two pages.
+
+## Style Rules
+
+- **Second person** ("you can...") for tutorials and guides.
+- **Third person** for reference and concept docs.
+- **Present tense, active voice.**
+- **Short paragraphs** — 3–4 sentences max. Long paragraphs scan poorly.
+- **Code blocks must be correct and ready for use.** Assume the reader
+  will copy them verbatim — no `todo`, no `fix in prod`, no untested
+  placeholders. If a value must be substituted, surface it with an
+  explicit callout immediately above the block.
+
+## Doc Lifecycle
+
+1. **Draft** under `docs/<bucket>/<slug>.md` with the right Diátaxis bucket.
+2. **Add to sidebar** in `sidebars.ts` if surfacing to users.
+3. **Run the docs site locally** (`npm start`) and proof at
+   `localhost:3000`.
+4. **Submit PR** — the docs CI runs link-checking and broken-image checks.
+
+## Why This Lives in a Skill, Not CLAUDE.md
+
+Doc-authoring conventions only matter when writing prose. Loading them
+into every Claude session in the docs repo would crowd out genuinely
+global rules. The skill auto-loads when it is needed; otherwise it sits
+idle.

CLAUDE.md

@@ -1,20 +1,19 @@
 # PPDS Docs
 
-Documentation site for Power Platform Developer Suite.
+Documentation site for Power Platform Developer Suite (Docusaurus).
+
+Governance for THIS file: **<https://github.com/joshsmithxrm/power-platform-developer-suite/blob/main/docs/CLAUDE-MD-GOVERNANCE.md>**.
 
 ## NEVER
 
-- Write marketing fluff - be technical and direct
-- Document features before they're implemented
-- Duplicate content that exists in code (link instead)
-- Use screenshots without alt text
+- Document a feature that is not yet implemented in PPDS.
+- Duplicate content that already exists in code or specs — link instead.
 
 ## ALWAYS
 
-- Write for the user's goal, not the feature
-- Include working code examples (test them!)
-- Link to source code for implementation details
-- Use consistent terminology (see `.claude/rules/branding.md`)
+- Test every code example before merge — broken examples are the #1 source of bug reports.
+- Link to source code for implementation details rather than re-explaining logic.
+- Use canonical terminology — see `.claude/rules/branding.md` for the name list.
 
 ## Commands
 
@@ -24,38 +23,7 @@ Documentation site for Power Platform Developer Suite.
 | `npm run build` | Production build |
 | `npm run typecheck` | TypeScript validation |
 
-## Doc Types (Diátaxis)
-
-| Type | Purpose |
-|------|---------|
-| Tutorial | Learning-oriented, step-by-step |
-| Guide | Task-oriented, goal-focused |
-| Reference | Information-oriented, complete |
-| Concept | Understanding-oriented, explains why |
-
-## Structure
-
-- `docs/getting-started/` - First 5 minutes
-- `docs/guides/` - How to... (task-oriented)
-- `docs/reference/` - CLI/Libraries/MCP reference
-- `docs/concepts/` - Architecture explanations
-
-## Key Files
-
-- `docusaurus.config.ts` - Site configuration
-- `sidebars.ts` - Navigation structure
-- `.claude/rules/branding.md` - Colors, voice, terminology
-
-## Style
-
-- Second person ("you can...")
-- Present tense, active voice
-- Code examples should be copy-pasteable
-- Short paragraphs (3-4 sentences max)
-
-## Blog Voice
+## Authoring
 
-- First person singular ("I discovered...")
-- Conversational but technical
-- Show the struggle, not just the solution
-- Include real numbers
+For Diátaxis classification, voice, and style: see the `write-docs` skill.
+For blog posts: see the `write-blog` skill.