菜单
Operating manual for documentation work in nexus-agents. Use when updating docs, adding new docs, changing doc pipeline, or troubleshooting doc issues. Triggers on "update docs", "add documentation", "doc pipeline".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | documentation-management |
| description | Operating manual for documentation work in nexus-agents. Use when updating docs, adding new docs, changing doc pipeline, or troubleshooting doc issues. Triggers on "update docs", "add documentation", "doc pipeline". |
| allowed-tools | Read, Edit, Write, Bash, Grep, Glob, Task |
Full specification: docops-spec.md
# 1. Edit canonical source
edit docs/architecture/MEMORY_SYSTEM.md # or relevant file
# 2. Verify docs are indexed
npx tsx scripts/check-docs-indexed.ts
docs/ directorytitle, description, tier, keywords, related_files)docs/README.mddocs/ops/docops-spec.md.claude/skills/documentation-management.md)npx tsx scripts/check-docs-indexed.ts
npx tsx scripts/generate-repo-index.ts --check
npx tsx scripts/inject-governance.ts check
| Source | Purpose |
|---|---|
docs/README.md | Human-readable index (SINGLE SOURCE OF TRUTH) |
docs/INDEX.yaml | Machine-parseable index |
docs/**/*.md | Canonical documentation |
Root *.md | Project entry points |
| Output | Generated By | From |
|---|---|---|
docs/interfaces/agent.md | generate-docs-content.ts | core/types/agent.ts |
docs/design/components.md | generate-docs-content.ts | src/ module scan |
docs/ops/docs-inventory.md | generate-docs-content.ts | ADR + MCP tool scan |
docs/reference/capabilities.md | generate-repo-index.ts | Source code |
docs/reference/tools/*.md | generate-tool-reference.ts | TOOL_MANIFEST + *InputSchema |
| CLAUDE.md tool index | inject-governance.ts | MCP tool files |
Auto-generates documentation sections that are derivable from source code:
the AgentRole interface, a module inventory, and the ADR / MCP tool counts.
Prevents drift by reading directly from the source of truth.
npx tsx scripts/generate-docs-content.ts # Generate all
npx tsx scripts/generate-docs-content.ts --check # CI validation
Generates capability index from source code. MCP tools are discovered by parsing
the canonical tools: [...] return array in mcp/tools/index.ts.
npx tsx scripts/generate-repo-index.ts # Generate index
npx tsx scripts/generate-repo-index.ts --check # CI validation
Injects MCP tool table into CLAUDE.md. Tool descriptions are defined in the
TOOL_DESCRIPTIONS map — add an entry there when registering a new MCP tool.
npx tsx scripts/inject-governance.ts inject # Update CLAUDE.md
npx tsx scripts/inject-governance.ts check # CI validation
The pipeline runs a family of jobs covering: TypeDoc freshness, capabilities.md regeneration, link validation, docs coverage, secrets scanning, DocOps skill sync, canonical-index enforcement, markdown lint, spell check, skills/index.yaml freshness, agents/index.yaml + gap-coverage check, and governance drift. Blocking-vs-warning status is declared per job in the workflow file.
All documentation MUST be indexed in docs/README.md.
docs/README.md is the ONLY permitted documentation index.
CI fails if generated files drift from canonical sources.
Changes to pipeline files require updating this skill and docs/ops/docops-spec.md.
Pipeline files:
scripts/generate-docs-content.tsscripts/generate-repo-index.tsscripts/inject-governance.ts.github/workflows/docs-check.ymlnpx tsx scripts/generate-docs-content.ts
git add docs/interfaces/agent.md docs/design/components.md docs/ops/docs-inventory.md
git commit -m "docs: regenerate source-derived docs"
npx lychee . --config lychee.toml to identify broken links# Run full validation suite locally
pnpm lint
pnpm typecheck
npx tsx scripts/generate-docs-content.ts --check
npx tsx scripts/generate-repo-index.ts --check
npx tsx scripts/inject-governance.ts check
Before committing documentation changes:
docs/README.mdnpx tsx scripts/generate-docs-content.ts --check passes (if types/module structure changed)npx tsx scripts/generate-repo-index.ts --check passes (if MCP tools added/renamed)npx lychee . --config lychee.tomlAdapted from paperclipai/paperclip doc-maintenance skill. Triggers: weekly cadence, post-release, after a major merge, or on explicit request ("audit docs", "doc drift").
User-facing docs that get stale fastest as the codebase moves:
README.md — features table, quickstart, prerequisitesdocs/README.md — canonical doc indexdocs/getting-started/INSTALLATION.md — install commands, Node/pnpm versionsdocs/getting-started/CONFIGURATION.md — env var table, config schemaCLAUDE.md — Canonical Paths table, MCP Tools table (auto-generated, but check the non-auto sections)Store the last-reviewed commit SHA in .doc-review-cursor (gitignored — it's local audit state, not project state). On each audit run:
LAST_SHA=$(cat .doc-review-cursor 2>/dev/null || echo "HEAD~200")
git log "$LAST_SHA"..HEAD --oneline --no-merges > /tmp/audit-window.log
After committing the audit fixes:
git rev-parse HEAD > .doc-review-cursor
Without the cursor, every audit re-reads the whole history → audits get skipped. With it, audits stay incremental and cheap.
From the audit window, only these commit prefixes warrant a doc check:
| Prefix | Action |
|---|---|
feat: / feat(...): | Check feature tables, README highlights, capability docs |
fix: containing breaking / API-removal | Check API reference, migration notes |
New top-level src/ directory | Check architecture overview, canonical paths |
chore(deps): major bumps | Check prerequisites + compat tables |
Ignore: refactor, test, chore(ci), docs, style — they don't shift user-facing surface.
Run the audit through this lens:
| Drift class | Signal |
|---|---|
| False negative | Shipped capability missing from feature/MCP tool/expert tables. Resolved design questions still marked TBD. Removed adapters/skills still listed. |
| False positive | "Coming soon" / "planned" features that have shipped. Cancelled items still on roadmap. Capability claims that contradict current implementation. |
| Quickstart breakage | npx/pnpm commands that don't work. Prerequisites pinning unsupported versions. Clone URL drift. Required env vars unmentioned. |
| Feature-table drift | ## MCP Tools Reference count mismatch. Adapter "Works with" table missing recently-added CLI. Skill index missing a new skill. |
For our auto-generated tables (CLAUDE.md MCP tools, capabilities.md, docs/interfaces/agent.md), drift is a generation-script bug, not a doc edit — file an issue against the script instead of editing the rendered output.
docs/audit-$(date +%Y%m%d)scripts/inject-governance.ts, scripts/generate-docs-content.ts, scripts/generate-repo-index.ts, etc.) — see Pipeline section aboveADRs capture the why behind significant technical decisions. Code shows what was built; ADRs explain why this way and what alternatives were rejected. They're the highest-leverage documentation in the repo for onboarding (humans and agents) and for evaluating future changes.
ADRs live in docs/adr/ with sequential numbering: 0001-foo.md, 0002-bar.md, …
# ADR-NNNN: <decision in present tense>
## Status
Proposed | Accepted | Superseded by ADR-MMMM | Deprecated
## Date
YYYY-MM-DD
## Context
What problem are we solving? What constraints (technical, organizational, time-bound) apply?
Cite the issue, vote, or incident that prompted the decision.
## Decision
The chosen approach, in 1-3 sentences.
## Alternatives Considered
Each as its own subsection. Pros, cons, and **why rejected**. Don't skip — the rejected
alternatives are how future readers understand the trade-off space.
## Consequences
Positive AND negative outcomes. What new constraints does this create?
What follow-up work falls out of this decision?
PROPOSED → ACCEPTED → (SUPERSEDED-BY-NNNN | DEPRECATED)
Status: line to Superseded by ADR-NNNN.CLAUDE.md, .rules/) — reference, don't duplicate| Excuse | Counter |
|---|---|
| "The code is self-documenting" | Code says how, not why. The why-this-not-that lives nowhere if not in an ADR or doc comment. |
| "I'll document it later" | Later never comes. The context decays within days; what felt obvious now will be a mystery to next-quarter-you. Document at decision time. |
| "We'll update the docs in the next release" | Drift compounds. By the next release, the doc says one thing, the code does another, and the audit gate fires (see #2225 audit). Update docs in the same PR as the code change. |
| "Comments lie, only code is truth" | Lies-in-comments is a culture problem, not a comments problem. Code can also lie (subtly broken implementations). Both need review. |
| "Nobody reads the docs anyway" | Future-you reads them. New contributors (human or agent) read them. The skill-tree of the project depends on them. |
| "It's just an internal API" | Internal APIs accumulate Hyrum's Law just like public ones (see api-and-interface-design). Internal docs prevent internal coupling. |
npx tsx scripts/check-docs-indexed.ts passesnpx markdownlint 'docs/**/*.md' '*.md'inject-governance.ts check fails)@deprecated references in docs/ after a removalPeriodically exercise ALL nexus-agents feature families end-to-end against a real task — research → synthesize → vote → plan → dev-pipeline → graph workflow → memory → audit — capturing ACTUAL outputs to validate that fixes, docs, and claims hold in real usage (the things unit tests miss: live voter panels, adapter routing, pipeline stage wiring, audit chains). Use after a release, weekly, when several fixes have landed since the last run, or on demand. Triggers on "e2e validation", "end-to-end validation", "dogfood the loops", "validate end to end", "real usage test", "periodic validation run", "full-loop validation".
Run the CI gates locally before pushing, so failures surface in seconds instead of one CI cycle at a time. Enumerates the checks in .github/workflows/, runs the locally-runnable subset in CI's order, and pins the local-vs-CI delta as a memory the first time you work in a repo. Use before `git push` / opening a PR, or when CI just failed on something your local gate missed. Triggers on "pre-push", "before push", "ci parity", "will ci pass", "local gate", "prepush", "pre-push check".
Review code changes following project standards and security guidelines. Checks for lint compliance, type safety, test coverage, and security issues. Use when reviewing PRs, auditing code, checking implementation quality, or running a blind pre-merge review pass before merging your own change. Triggers on "review code", "code review", "check this", "audit", "PR review", "pre-merge review", "blind reviewer", "before merge".
Execute a release following project standards. Use when publishing a new version, creating release tags, or deploying. Triggers on "release", "publish", "version bump", "create release".
Improve an existing technical doc in-place via a phased Audit → Research → Rewrite → Validate workflow. Calls docs-review for audit and validate; never re-derives scoring. Applies answer-first H2s, citation capsules, and info-gain markers per .rules/docs-rubric.md. Use when the user says "rewrite docs", "improve this doc", "optimize doc", "docs rewrite".
Score a technical doc (RFC, ADR, README, CLAUDE.md, blog-style post) against the 5-category 100-point rubric in .rules/docs-rubric.md. Read-only audit. Surfaces top issues by severity. Defers to existing user-level skills (blog-llm-tells, blog-factcheck, blog-overlap, blog-argument-shape, blog-pre-publish) for prose-quality dimensions rather than re-deriving them. Use when the user says "review docs", "audit docs", "score this doc", "doc quality", "docs review".