@@ -0,0 +1,79 @@
1+---
2+name: technical-documentation
3+description: Build and review high-quality technical docs as well as agent instruction files in your repository.
4+license: MIT
5+metadata:
6+source: "https://github.com/vincentkoc/dotskills"
7+---
8+9+# Technical Documentation
10+11+## Purpose
12+13+Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files.
14+15+## When to use
16+17+- Creating or overhauling docs in an existing product/codebase (brownfield).
18+- Building evergreen docs meant to stay accurate and reusable over time.
19+- Reviewing doc diffs for structure, clarity, and operational correctness.
20+- Running full-repo documentation audits that must include both governance files and product docs surfaces (`docs/`, `README*`, `.md/.mdx/.mdc`, Fern/Sphinx/Mintlify-style sources).
21+- Updating or reviewing AGENTS.md and/or CONTRIBUTING.md to keep agent and contributor workflows aligned with current repo practices.
22+- Improving repository onboarding/docs that include contribution instructions, issue templates, PR flow, and review gates.
23+- Designing governance documentation strategy for repos with alias instruction files (for example `CLAUDE.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`) where `AGENTS.md` is treated as canonical when present and aliases should be kept as compatibility surfaces.
24+- Diagnosing agent-file drift where teams had to prompt iteratively to surface missing files, broken commands, or policy conflicts.
25+- Applying repository-specific documentation overlays, including OpenClaw page-type, docs IA, preservation, and validation rules when present.
26+27+## Workflow
28+29+1. Classify task: `build` or `review`; context: `brownfield` or `evergreen`.
30+2. Inventory full documentation scope early (governance + product docs): AGENTS/CONTRIBUTING/aliases plus docs directories, framework sources, and root/module READMEs.
31+3. Detect multilingual scope (README/docs in multiple languages) and define required parity level.
32+4. Read `references/agent-and-contributing.md` for agent instruction and `CONTRIBUTING.md` workflow rules (inventory, canonical/alias mapping, dual-mode balance, deliverable standards, and precedence/conflict handling).
33+5. Read `references/principles.md` for the governing ruleset (Matt Palmer & OpenAI).
34+6. For OpenClaw docs work, read `references/openclaw.md` before the build/review playbook.
35+7. For build tasks, follow `references/build.md`.
36+8. For review tasks, follow `references/review.md` and proactively detect issues without waiting for repeated prompts.
37+9. For complex or high-risk tasks (build or review), it is acceptable to run longer, deeper, and more exhaustive investigations when needed for confidence.
38+10. When available, use sub-agents for bounded parallel discovery/review work, then merge outputs into one coherent final deliverable.
39+11. Use `references/tooling.md` when platform/tooling choices affect recommendations.
40+12. Run a proactive issue sweep for both governance and docs-content surfaces, and fix high-confidence defects in the same pass unless explicitly asked for report-only mode.
41+13. In brownfield mode, prioritize compatibility with current docs IA, tooling, and release state.
42+14. In evergreen mode, prioritize timeless wording, update strategy, and durable structure.
43+15. Return deliverables plus validation notes, parity status, and remaining gaps.
44+45+## Sub-agent orchestration guidance
46+47+Prefer sub-agents when the repo is large or the requested change set is broad; use them by default for repo-wide, multi-framework, or high-conflict work.
48+49+- `inventory-agent` -> `agents/inventory-agent.md` (`fast` / Claude `haiku`): file/config discovery, coverage map, and missing-path checks.
50+- `governance-agent` -> `agents/governance-agent.md` (`thinking` / Claude `sonnet`): AGENTS/CONTRIBUTING/alias precedence, conflicts, and policy drift.
51+- `docs-framework-agent` -> `agents/docs-framework-agent.md` (`thinking` / Claude `sonnet`): framework config, relative path base, and file-path vs URL-path mapping checks.
52+- `synthesis-agent` -> `agents/synthesis-agent.md` (`long` / Claude `opus`): merge sub-agent outputs into one prioritized fix plan and unified precedence model.
53+54+## Inputs
55+56+- Doc type (tutorial, how-to, reference, explanation) and audience.
57+- File scope or diff scope.
58+- Docs framework/tooling constraints (Fern, Mintlify, Sphinx, etc.).
59+- Build/review mode and brownfield/evergreen intent.
60+- Target agent and human compatibility intent.
61+- Docs framework surfaces in scope (for example Fern, Sphinx, Mintlify, Markdown/MDX/MDC/RST/RSC files).
62+- Desired investigation depth/time budget (quick pass vs exhaustive review).
63+- Execution mode (`single-agent` or `sub-agent-assisted` when available).
64+- Remediation mode (`apply-fixes` by default, or `report-only` when requested).
65+- Multilingual scope: source-of-truth language, target locales, and parity expectations.
66+- Repository-specific overlay constraints, if any.
67+68+## Outputs
69+70+- Updated draft or review findings with clear next actions.
71+- Validation notes (what was checked, what remains).
72+- Navigation/maintenance recommendations for long-term quality.
73+- Governance-doc alignment summary when AGENTS/CONTRIBUTING were touched.
74+- Agent instruction-surface map (primary file, alias files, Codex/Claude/Cursor handling plan).
75+- Documentation-surface coverage map (what was reviewed under `/docs`, README hierarchy, and framework-specific source trees).
76+- Autodetected issue list with applied fixes (or explicit report-only findings).
77+- Delegation notes when sub-agents were used (scope delegated and how findings were merged).
78+- Multilingual parity note (in-sync, partial with rationale, or intentionally divergent).
79+- Repository-specific overlay notes when one was used.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。