feat: add recce-docs-guide local skill and update CLAUDE.md

[kentwelcome]

Summary

• Add .claude/skills/recce-docs-guide.md — a local skill that handles writing, editing, and reviewing documentation with MkDocs-specific conventions
• Update CLAUDE.md — refresh file structure table and add Plugin Dependency section for recce-team plugin
• Update .gitignore — ignore .claude/superpowers/ and .claude/settings.local.json
• Apply recce-team:writing-content standards to MCP Server and Claude Plugin pages (PR docs: Update MCP Server and Claude Plugin pages for new tools #93 review)

Resolves GTM-536

Design

The skill layers on top of the recce-team:writing-content plugin:

• Local skill owns: MkDocs conventions (image format, admonitions, page template, heading styles, nav updates, redirects)
• Plugin provides: Voice, formatting, terminology, QA, and AISEO reviews
• Local claude/ files kept: Writing principles (ICP definitions, audience strategy), terminology (confusion analysis, clarification patterns), and knowledge base (site map) contain unique docs-specific content not in the plugin

The skill auto-triggers on any work in docs/, mkdocs.yml, or claude/ and routes to:

• Lightweight path for small edits (1-2 pages, no nav changes)
• Full path for major changes (new pages, restructuring, 3+ pages)

PR #93 content review

Applied recce-team:writing-content skill as a test case for the new docs guide. Changes to mcp-server.md and claude-plugin.md:

Issue	Fix
"single-environment mode" uses "environment"	→ "single-source mode" (terminology guide)
Duplicated single-source mode note	Removed duplicate (state details once)
"Next Steps" heading	→ "Next steps" (sentence case for H2)
Long feature list in claude-plugin.md	Tightened for readability
"all modes" vague in mcp-server.md	Clarified tool grouping by function

Test plan

• Verify .claude/skills/recce-docs-guide.md is detected as a skill in Claude Code
• Verify the skill triggers when editing files under docs/
• Verify pre-flight check prompts plugin installation if recce-team is not installed
• Verify CLAUDE.md renders correctly with updated file structure table
• Verify mkdocs build passes with MCP/Claude Plugin page changes

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a repo-local Claude Code skill to standardize documentation work for this MkDocs site, updates contributor guidance, and ignores local Claude config artifacts.

Changes:

• Add .claude/skills/recce-docs-guide.md to define MkDocs-specific documentation conventions and a plugin pre-flight check.
• Update CLAUDE.md file structure table and add a recce-team plugin dependency/install section.
• Update .gitignore to ignore local Claude Code state/config files.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

File	Description
CLAUDE.md	Updates repo documentation guidance and adds plugin installation instructions.
.gitignore	Ignores local-only Claude Code files/directories to avoid repo churn.
.claude/skills/recce-docs-guide.md	Introduces a local skill defining docs workflows and MkDocs formatting conventions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ijac13]

I used to use recce-team to write the doc and then create a PR in recce-docs.
Do we need to have Claude here? I want to keep single source of truth about the voice, context, format..etc.

[ijac13]

Why do we need this here? It feel duplicated with https://github.com/DataRecce/recce-team/blob/main/recce-team/context/product/terminology.md and https://github.com/DataRecce/recce-team/blob/main/recce-team/context/product/recce-context.md

[gcko]

Findings

Summary

This PR adds .claude/skills/recce-docs-guide.md (188 lines), refreshes CLAUDE.md, gitignores .claude/superpowers/ and .claude/settings.local.json, ships a 64-line .github/copilot-instructions.md (NOT in GTM-536 scope), and tightens two docs pages from the PR #93 review. GTM-536 scope is substantially delivered: the local skill exists with pre-flight/scope-routing/MkDocs conventions, CLAUDE.md is updated, and the .gitignore adds match. The docs/superpowers/ → .claude/superpowers/ move from the ticket is already complete on main (the directory is gone at the PR head; only the gitignore add remains here, which is correct). The central question — whether the layered-skill design preserves a single source of truth — is the substantive review issue. As written, the boundary leaks badly and partially contradicts the PR's stated design.

HIGH

H1 — .github/copilot-instructions.md directly contradicts the PR's own "single source of truth" claim.
File: .github/copilot-instructions.md:7-50 (entire Terminology + Voice + MkDocs formatting + Content strategy sections).
The PR description says: "Plugin provides: Voice, formatting, terminology, QA, and AISEO reviews" — yet this new file re-states all of those rules inline as plain prose for Copilot to consume. Lines 11-25 duplicate recce-team/context/product/terminology.md. Lines 27-34 duplicate recce-team/skills/writing-content/reference/voice.md (omit-needless-words, active voice, sentences under 20 words, no false-humility list — verbatim themes). Lines 50-56 duplicate recce-team/skills/writing-content/reference/doc.md content-strategy rules ("Cloud-first", "lead with value", "single source of truth"). @ijac13 already flagged this on the inline comment at line 1 ("Why do we need this here? It feel duplicated with [terminology.md] and [recce-context.md]") and the author has not replied to that comment as of the head SHA. This file is also outside GTM-536 scope. Recommendation: drop the file, OR shrink it to 2-3 lines that point Copilot at the plugin + the local skill (the same two-tier indirection the skill itself uses). Until this is resolved, @ijac13's CHANGES_REQUESTED review stands on its merits — the PR concretely fragments the source of truth it claims to preserve.

MEDIUM

M1 — "Navigation updates" section in the local skill duplicates the recce-team plugin verbatim.
File: .claude/skills/recce-docs-guide.md:166-176 (the "Navigation updates" + redirect_maps YAML example).
The plugin's recce-team/skills/writing-content/reference/doc-update.md Phase 4 ("Implementation") already owns mkdocs.yml nav updates, the plugins > redirects > redirect_maps pattern, the same redirect YAML example, AND a complete redirect-needed-when checklist. The new skill duplicates the YAML example without referencing or extending the plugin. The PR design table claims "Local skill owns: ... nav updates, redirects" but they already live in the plugin. Either the plugin's doc-update.md should defer to the local skill (and be slimmed in recce-team), or the local skill should defer to the plugin and skip the duplicate YAML.

M2 — Page structure template competes with the plugin's three-template system.
File: .claude/skills/recce-docs-guide.md:75-100 ("Page structure template").
The plugin's recce-team/skills/writing-content/reference/doc.md defines three distinct, mandatory templates: Concept Doc Writer, Tutorial Doc Writer, Reference Doc Writer — each with its own required structure, quality checklist, and AISEO gate. The new local skill collapses this into a single generic template ("Value-first conceptual overview / Step-by-step guide / Common scenarios / Troubleshooting / What's next"). An author following the local skill's lightweight path skips the plugin's three-template choice entirely. This is a real conflict, not just overlap. Recommendation: drop the template from the local skill and route all "structure" decisions through recce-team:writing-content (which also routes to the right of the three templates).

M3 — "Bold usage" guideline is voice/formatting territory.
File: .claude/skills/recce-docs-guide.md:157 ("Bold usage. Use bold sparingly.").
This is a voice/formatting concern, not an MkDocs concern. The plugin's voice.md and formatting.md are the canonical source. Either move the rule into the plugin or drop it from the local skill — leaving it here is the same fragmentation @ijac13 flagged.

LOW

L1 — Pre-flight plugin check is a soft prompt-level convention, not enforcement.
File: .claude/skills/recce-docs-guide.md:13-27.
The instruction "Do not proceed without the plugin" is text shown to the model; Claude Code skills cannot verify another skill's presence at runtime. If the user has not installed recce-team, the model may still proceed using the local skill alone. Worth a one-line caveat in the skill, or a note that the check is best-effort. Not a blocker — the soft check still raises the salience of the dependency.

L2 — CLAUDE.md drops the Knowledge Base pointer entirely.
File: CLAUDE.md diff - block (the removed ## Knowledge Base / → claude/KNOWLEDGE_BASE.md section).
The new skill at .claude/skills/recce-docs-guide.md:62 ("claude/KNOWLEDGE_BASE.md — site map / section index") still depends on this file existing, but a contributor reading CLAUDE.md no longer learns about it. The replacement "Plugin Dependency" section is fine, but losing the Knowledge Base pointer is a small discoverability regression. Recommendation: keep both sections, or add a single line under the file-structure table referencing claude/KNOWLEDGE_BASE.md.

L3 — Heading capitalization rule lives in two places.
File: .claude/skills/recce-docs-guide.md:103-106 and .github/copilot-instructions.md:38-39.
"H1: Title Case / H2+: sentence case" appears in both new files, with no shared definition. If the rule changes, two files must be updated. This is the smaller version of M3 / H1.

NIT

N1 — .gitignore overlap risk.
File: .gitignore:8 (.claude/settings.local.json).
Claude Code's default templates often already cover this; double-ignore is harmless but worth a quick verify. If a project-level .gitignore template is intended, prefer documenting why these specific paths are gitignored (a one-line comment) rather than the bare entries.

N2 — Image-format fix from earlier review is correctly applied at head.
File: .claude/skills/recce-docs-guide.md:108-127 (subdirectory + top-level path forms).
Both the ../assets/images/... and assets/images/... forms are shown with examples. Closes the Copilot inline comment from earlier in the review thread (commit 509c1ef). Good.

Position on the layered-skill design (responding to @ijac13)

@ijac13's CHANGES_REQUESTED is substantively correct as the PR stands today, and the strongest evidence is in the PR itself:

1. The plugin's recce-team/skills/writing-content/reference/doc.md (12 KB) and doc-update.md (8.8 KB) already own the docs workflow, including three doc-type templates and the full implementation phase (branch, draft, mkdocs.yml nav, redirects, PR body). The new local skill duplicates the easy parts of that (template, nav, redirects) and routes the hard parts (QA, AISEO) back to the plugin. The split isn't "MkDocs mechanics vs voice" — it's "thin generic doc workflow vs full plugin doc workflow," and the boundary is unclear enough that an author can pick the lightweight path and skip the plugin's three-template choice and QA/AISEO entirely.
2. .github/copilot-instructions.md is the smoking gun: it restates terminology, voice, MkDocs formatting, and content strategy inline in this repo. Whatever the layered design says about "plugin owns voice," this file does the opposite. It is literally a second source of truth.

Where the design IS defensible — and the PR can address @ijac13 substantively:

• Pre-flight plugin check (M-tier helpful, only meaningful in this repo).
• Scope detection (lightweight vs full path) — genuinely repo-local; the plugin's doc-update.md is heavy gates that would over-engineer typo fixes.
• <figure markdown> + .shadow figure format with both path forms — MkDocs Material syntax, doesn't fit a content-team plugin used for blog/social/PR.
• !!! tip / !!! note / !!! warning / !!! info admonitions — same.
• Code-block conventions (shell, diff) — same.

Recommended fix to land this PR:

1. Drop .github/copilot-instructions.md or shrink it to a 2-line pointer at recce-team and the local skill. Reply to @ijac13's inline comment with reasoning.
2. Trim the local skill to: pre-flight check, scope detection, figure format, admonitions, code blocks. Drop "Page structure template," "Navigation updates," "Bold usage," and "Heading capitalization." Each of those gets a one-line "see recce-team:writing-content (reference/doc.md / reference/doc-update.md / reference/formatting.md)" pointer.
3. Reply to @ijac13's top-level CHANGES_REQUESTED comment with the revised boundary table — concrete, file-by-file. The current PR description's design table is aspirational; the diff doesn't match it.

After those changes, the layered design becomes a defensible single-source-of-truth split, and @ijac13's concern is addressed by structure, not by hand-waving.