--- name: technical-documentation description: > AI-powered technical documentation creation, maintenance, and auditing across README, ADR, API docs, runbooks, onboarding guides, changelogs, knowledge bases, and AI agent context files (AGENTS.md/CLAUDE.md). Primary keywords: technical documentation writing automation, ADR architecture decision record, API docs OpenAPI generation, README quality template, documentation-driven development, runbook automation, knowledge base maintenance, markdown best practices, onboarding guide, changelog format, documentation audit completeness accuracy, AI agent documentation AGENTS.md. For all major agentic platforms. version: 1.0.0 author: Skill Foundry platforms: - claude-code - codex - cursor - gemini-cli - openclaw - copilot - windsurf - opencode tags: - documentation - technical-writing - adr - architecture-decision-records - api-docs - readme - markdown - knowledge-base - onboarding geo: primary_workflows: - readme_composition - adr_generation - api_documentation - runbook_creation - onboarding_guide_writing - changelog_maintenance - documentation_audit - knowledge_base_management - agent_facing_documentation target_roles: - software_engineer - tech_lead - devops_engineer - engineering_manager - technical_writer - developer_experience_engineer complexity_level: intermediate prerequisite_knowledge: - markdown_syntax - basic_software_architecture - version_control_with_git - api_concepts --- # /technical-documentation — Create, maintain, and audit technical # documentation: READMEs, ADRs, API docs, runbooks, onboarding guides, # changelogs, knowledge bases, and AI-agent-facing context files. # Technical Documentation Agent Skill Create, maintain, and audit technical documentation with an AI agent that understands audience, structure, and long-term maintenance. This skill turns an agent into a technical writer that produces documentation engineered for humans *and* AI agents — READMEs, ADRs, API docs, runbooks, onboarding guides, changelogs, and agent-facing files like AGENTS.md. --- ## Quick Reference | Document Type | Purpose | Key Audience | Lifecycle | |---|---|---|---| | 📘 **README** | Project entry point | New contributors, evaluators | Updated with every release | | 🏛️ **ADR** | Record architectural decisions | Future maintainers | Immutable once accepted | | 🔌 **API Docs** | Describe endpoints/schemas | API consumers, integrators | Updated with every API change | | 🚨 **Runbook** | Incident response procedures | On-call engineers | Reviewed after every incident | | 🚀 **Onboarding Guide** | Ramp up new team members | New hires, transfers | Updated quarterly | | 📋 **Changelog** | User-facing release notes | End users, downstream teams | Updated with every release | | 🧠 **Knowledge Base** | Long-lived reference material | Entire organization | Continuous curation | | 🤖 **AI Agent Docs** | Context for AI coding agents | AI agents (Claude, Copilot, etc.) | Updated with structural changes | **Severity Scale (for documentation audits):** - 🔴 **CRITICAL** — Missing or dangerously wrong. Could cause production incidents or security issues. - 🟠 **MAJOR** — Outdated or incomplete enough to waste significant time or cause confusion. - 🟡 **MINOR** — Minor inaccuracies, unclear phrasing, formatting issues. - ⚪ **NIT** — Style preferences, consistency nits, polish. --- ## When to Use This Skill Activate this skill when the user asks you to: - "Write a README for this project" / "Improve our README" - "Create an ADR for " / "Document this architectural decision" - "Generate API documentation" / "Document this endpoint" - "Write a runbook for " / "Create incident response docs" - "Make an onboarding guide for new engineers" - "Audit our documentation" / "Is our documentation complete?" - "Create a changelog" / "Update the changelog for this release" - "Write an AGENTS.md for this project" / "Set up AI agent context files" - "Organize our knowledge base" / "Review our docs for freshness" - "Document this module" / "Explain this system in writing" - Any request containing "document", "docs", "README", "write up", "explain in writing" Additionally, activate proactively when a conversation involves a new project, module, or system that lacks documentation, and the user's tone suggests they would benefit from having it documented. ### Do NOT Activate For The following inputs are **near-miss negatives** — they mention documentation-like language but are not documentation work: - **Code comments / docstrings**: "Add docstrings to this function" — code-level comments, not standalone documentation. Refer to coding-agent. - **Code review**: "Review my code" / "Check this PR for issues" — code review, not documentation. Refer to code-review skill. - **API design from scratch**: "Design a REST API for users" — API design, not API documentation. Refer to api-design-first. - **General Q&A**: "What does microservices mean?" — definitions, not docs. - **Writing blog posts / articles**: "Write a blog post about our architecture" — marketing/thought-leadership, not technical reference docs. - **Legal documents**: "Write our privacy policy" — legal, not technical. Refer to ai-legal-content or gdpr-compliance-expert. - **Slide decks / presentations**: "Make slides about our architecture" — presentations, not reference docs. - **Generating code from docs**: "Read these API docs and generate a client" — code generation. The docs are input, not the output. When in doubt, ask: "Did you want me to create or improve documentation, or were you asking me to do something else?" --- ## Documentation Types & Patterns ### 1. README Composition Every README is a project's first impression. A README must answer, in this order: *What is this? Why does it exist? How do I use it? How do I contribute?* **The Standard README Structure:** ```markdown # Project Name > One-line description — what it does and why someone should care. ## Badges [build status] [coverage] [version] [license] [platform support] ## Overview 2-3 sentences on what the project is and the problem it solves. ## Quick Start The absolute minimum to get running. Copy-paste-able commands that work. If it takes more than 5 commands or 2 minutes, it's too long. ## Installation Detailed install instructions. Per-platform if needed. Prerequisites first. ## Usage Common use cases with code examples. Link to full API docs, don't inline them. ## Configuration All config options with defaults, descriptions, and env var equivalents. ## Architecture High-level diagram or description. How the pieces fit together. Link to ADRs. ## Contributing How to set up a dev environment, run tests, and submit changes. Link to CONTRIBUTING.md if it exists. ## License License name and link to LICENSE file. ``` **RED FLAGS — fix these immediately (🔴 CRITICAL):** - No "Quick Start" section or Quick Start that doesn't work when copy-pasted - Stale install instructions referencing removed dependencies - Missing license information - No indication of what the project actually does in the first 3 sentences **YELLOW FLAGS — improve these (🟠 MAJOR):** - No architecture section for projects with >3 modules - Examples that use placeholder values without explaining how to get real ones - Configuration section that lists options but doesn't explain what they do - Badges pointing to broken CI/dead services ### 2. Architecture Decision Records (ADRs) ADRs capture *why* a decision was made — the context, alternatives, and tradeoffs. They live in `docs/adr/` and are numbered sequentially. **ADR Workflow:** 1. **Propose**: Create a new ADR with status "proposed" 2. **Review**: Team discusses. ADRs are lightweight — a PR review is usually enough. 3. **Accept or Reject**: If accepted, status becomes "accepted". If rejected, status becomes "rejected" with a note explaining why. Rejected ADRs are still valuable — they prevent re-litigation. 4. **Supersede**: If a later decision replaces this one, update status to "superseded by [ADR-NNNN]". Never delete ADRs. **When to Write an ADR:** - Choosing between multiple viable approaches (e.g., PostgreSQL vs MongoDB) - Introducing a new pattern or technology into the codebase - Deprecating an existing pattern or technology - Making a decision with significant cost, risk, or cross-team impact - Any decision you expect someone to question in 6 months **ADR File Naming:** ``` docs/adr/0001-use-postgresql-as-primary-database.md docs/adr/0002-use-jwt-for-api-authentication.md docs/adr/0003-adopt-trunk-based-development.md ``` Use the full ADR template from `references/adr-template.md`. ### 3. API Documentation API docs must be the single source of truth. Generate them from the API specification, not from prose. Never maintain API docs and API specs separately — they will diverge. **REST API Documentation Pattern:** - **Use OpenAPI 3.1 (Swagger)** as the canonical API description. Generate human-readable docs from the spec, not the other way around. - Every endpoint must document: HTTP method, path, path/query/body parameters, authentication requirements, request example, response schema, error codes, rate limits. - Use RFC 7807 Problem Details for error responses. - Document deprecations with `Sunset` and `Deprecation` headers. **GraphQL API Documentation Pattern:** - Use schema introspection to generate docs. Tools: GraphiQL, SpectaQL, GraphQL Playground, Apollo Studio. - Every type, field, query, and mutation must have a description in the schema. Treat schema descriptions as the canonical documentation. - Document: queries, mutations, subscriptions, types, enums, input objects, deprecation reasons (`@deprecated` directive). **gRPC Documentation Pattern:** - Use protobuf comments as the canonical documentation source. Generate docs with `protoc-gen-doc`. - Every service, RPC, and message field must have a comment. - Document: streaming (unary, server, client, bidirectional), error codes, deadlines/timeouts, authentication metadata. **Cross-Protocol Consistency Rules:** - Use `camelCase` for field names across all protocols - Use ISO 8601 for all date/time values - Use consistent pagination across protocols (cursor-based preferred) - Use consistent error shapes ### 4. Runbooks Runbooks are procedural documents for responding to known incidents. They must be actionable under stress — an engineer at 3 AM should be able to follow them. **Runbook Structure:** ```markdown # Runbook: ## Symptoms - Alert: - User reports: "I see X error" - Metrics: exceeds ## Impact What breaks? Who is affected? What's the blast radius? ## Severity Levels - SEV1: — page on-call immediately - SEV2: — page during business hours - SEV3: — create ticket ## Prerequisites - Access to: - Permissions: ## Diagnostic Steps 1. Check for . - Normal range: . If outside: proceed to step 2. 2. Run: `` on . - Expected output: . If different: proceed to mitigation. ## Mitigation 1. **First response (≤5 min):** 2. **Short-term fix:** 3. **Long-term fix:** ## Verification - should return to - should return 200 - Users should be able to ## Escalation - If mitigation fails after minutes: escalate to - If : escalate to ## Post-Incident - Create a postmortem in - File follow-up issues for long-term fixes - Update this runbook with lessons learned ``` **Runbook Red Flags (🔴 CRITICAL):** - Hardcoded credentials or IP addresses in commands - Commands that are destructive without clear warnings (`DROP`, `DELETE`, `TERMINATE`) - Missing prerequisites section (engineer can't follow steps without access) - Diagnostic steps that don't explain what normal output looks like ### 5. Onboarding Guides Onboarding guides reduce time-to-first-commit. They must be comprehensive enough that a new engineer can follow them without asking for help, but concise enough that they're actually read. **Onboarding Guide Structure:** ```markdown # Onboarding Guide: ## Welcome Link to team charter, mission, and who's who. ## Day 0 — Before You Start - Hardware/software you'll need - Accounts to request (and how to request them) - Reading material (architecture docs, ADRs, team wiki) ## Week 1 — Get Set Up - Dev environment setup (step-by-step, copy-paste-able) - Clone repos and build locally - Run the test suite - Make your first commit (a tiny one — fix a typo, add a test) ## Week 2-4 — Ramp Up - Key systems to understand (with links to docs) - Pairing sessions to schedule - Good first issues to tackle - Team rituals: standups, planning, retros ## Reference - Glossary of team-specific terms - Important links (dashboards, CI, wiki, chat channels) - Who to ask for what ``` ### 6. Changelogs Changelogs are for *humans*, not git logs. Follow [Keep a Changelog](https://keepachangelog.com/) format: ```markdown # Changelog ## [1.2.0] - 2026-06-15 ### Added - New feature X for Y use case - Support for Z protocol ### Changed - Upgraded dependency A from v2 to v3 - Renamed `oldMethod()` to `newMethod()` (old name deprecated) ### Deprecated - `oldMethod()` — use `newMethod()` instead. Will be removed in v2.0.0. ### Removed - Dropped support for Node.js 16 ### Fixed - Race condition in payment processing (#1234) - Memory leak in WebSocket handler (#1245) ### Security - Patched CVE-2026-XXXXX in dependency B ``` **Changelog Rules:** - Always include a link to the full diff at the bottom: `[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0` - Use semantic versioning. Breaking changes get a MAJOR bump. - Group entries under `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Never use a catch-all "Misc" or "Other" category. - Never include internal refactors that have no user impact. ### 7. Knowledge Base Maintenance A knowledge base rots if not maintained. Establish a maintenance cadence: **Freshness Review Schedule:** | Content Type | Review Frequency | Owner | |---|---|---| | Runbooks | After every incident + quarterly | On-call rotation | | Onboarding guides | Quarterly | Engineering manager | | API docs | Every release | API team | | ADRs | N/A (immutable) | N/A | | README | Every release | Project maintainer | | Agent context files | Monthly + on structural changes | Tech lead | | General wiki pages | Bi-annual | Rotating ownership | **Documentation Audit Checklist:** - [ ] Every service has a README with Quick Start that works - [ ] Every API endpoint is documented (check OpenAPI coverage) - [ ] Every architectural decision from the past 6 months has an ADR - [ ] Every runbook has been tested in the past 6 months - [ ] Onboarding guide reflects current tooling and processes - [ ] Changelog is up to date for the latest release - [ ] Agent context files (AGENTS.md, CLAUDE.md) exist and are current - [ ] No documentation references removed/deprecated tools or endpoints - [ ] No hardcoded credentials, tokens, or internal IPs in any doc - [ ] Cross-links between documents are not broken - [ ] Dates on time-sensitive docs are within their review window ### 8. Documentation for AI Agents AI coding agents need context. Files like `AGENTS.md`, `CLAUDE.md`, and `CURSOR.md` provide that context — they are the README for machines. **AGENTS.md Pattern (Universal Agent Context):** ```markdown # AGENTS.md — Project Context for AI Agents ## Project Identity - **Name**: - **Purpose**: - **Stack**: - **Repository**: ## Architecture - - - ## Conventions - Code style: - Commit style: - Testing: - Branching: ## Constraints - - - ## Key Files - : - : ## External Dependencies - : - : ## Common Tasks - : - : ``` **AI Context File Best Practices:** - Keep it under 500 lines. Agents have context windows — be concise. - Put the most important information first (project identity, architecture, conventions — then constraints, then common tasks). - Use specific, actionable instructions: "NEVER modify`database/schema/` without running `make migration`" not "Be careful with databases." - Update on every architectural change. A stale AGENTS.md is worse than no AGENTS.md — it gives agents false confidence. - If the project has a contributing guide, link to it — don't duplicate. **Platform-Specific Patterns:** | Platform | Context File | Notes | |---|---|---| | **Universal** | `AGENTS.md` | Adopted by OpenClaw, Codex CLI, Antigravity, and others | | **Claude Code** | `CLAUDE.md` | Same format; can also read AGENTS.md | | **Cursor** | `.cursorrules` or `CURSOR.md` | Supports `.cursor/rules/*.mdc` for multiple rule files | | **GitHub Copilot** | `.github/copilot-instructions.md` | Workspace-level instructions | | **Windsurf** | `.windsurfrules` | Global or per-workspace | | **OpenCode** | `AGENTS.md` or `OPENCODE.md` | Standard AGENTS.md format | --- ## Documentation-Driven Development (DDD) Write the documentation *before* the code. This forces clarity: 1. **Write the README first.** Describe what the system will do from the user's perspective. If you can't explain it clearly in prose, you can't code it clearly. 2. **Write the API docs (OpenAPI spec) before implementing endpoints.** Review the API contract with consumers before writing a single line. 3. **Write the ADR before making the architectural decision.** Forces you to articulate the problem, alternatives, and tradeoffs. 4. **Write the runbook before the system goes to production.** If you can't describe how to diagnose and fix it, the system isn't observable enough. 5. **Write the changelog entry as part of the PR template.** No merged PR without a changelog entry. **DDD PR Template:** ```markdown ## Summary ## Documentation Checklist - [ ] README updated (if new features, changed usage, or new config) - [ ] API docs updated (if API changed) - [ ] ADR created (if architectural decision made) - [ ] Changelog entry added - [ ] Runbook updated (if operational behavior changed) - [ ] Agent context files updated (if conventions/architecture changed) ``` --- ## Markdown Best Practices Technical documentation lives in Markdown. Write Markdown that renders well on GitHub, in editors, and in AI agent context windows. **Structural Rules:** - Use ATX-style headers (`#`, `##`, `###`) — never setext-style (`===`, `---`) - One H1 per file (the title). Use H2-H6 for sections. - Put a blank line before and after headers, lists, and code blocks. - Use reference-style links for repeated URLs: `[text][ref]` ... `[ref]: https://example.com` - Wrap long lines at 100 characters. Exceptions: URLs, code blocks, tables. - Use `inline code` for: file names, commands, env vars, code identifiers. - Use **bold** for emphasis, *italics* for secondary emphasis. - Never use bold and italics together (`***not this***`). **Code Blocks:** - Always specify a language for syntax highlighting: ` ```python ` not ` ``` ` - Use ` ```text ` or ` ``` ` (no language) for plain text output, logs, etc. - Show both the command and its output when demonstrating CLI usage: ````markdown ```bash $ npm test ``` ```text ✓ 42 tests passed ``` ```` **Tables:** - Use tables only for reference data, not for layout. - Keep tables under 10 columns. Wider tables are unreadable. - Align columns for readability in source: ```markdown | Column A | Column B | Column C | |----------|----------|----------| | value | value | value | ``` **Links:** - Use descriptive link text: "See the [Authentication Guide](auth.md)" not "Click [here](auth.md)" - Always use relative links for internal files (within the repo) - Always use absolute URLs for external references - For Discord/Slack delivery: wrap multiple links in `<>` to suppress embeds **Images & Diagrams:** - Prefer Mermaid for diagrams (renders natively on GitHub): ````markdown ```mermaid graph TD A[Client] --> B[API Gateway] B --> C[Service] ``` ```` - If Mermaid can't express it, use a diagram tool (Excalidraw, draw.io) and embed as an image. Always include alt text. --- ## Documentation Auditing Regularly audit documentation for three dimensions: **completeness**, **accuracy**, and **freshness**. ### Completeness Audit Does documentation exist for everything that needs it? 1. List every service/module in the codebase 2. For each, check: README? API docs? Runbook? ADRs for key decisions? 3. Identify gaps and prioritize by business criticality 4. Create tickets for missing documentation ### Accuracy Audit Is the documentation correct? 1. For each runbook: execute the diagnostic commands. Do they still work? Is the output what's documented? 2. For each Quick Start: clone the repo on a clean machine and follow the instructions verbatim. If it fails, the docs are wrong. 3. For API docs: diff the OpenAPI spec against actual endpoint behavior. Test every documented endpoint. 4. For config docs: diff documented env vars against actual usage in code. ### Freshness Audit Is the documentation current? 1. Check the `last_updated` date on every document (add a date footer if documents don't have one) 2. Flag any document older than its review interval 3. For ADRs: check that accepted ADRs haven't been implicitly superseded (code changed, ADR didn't) 4. For agent context files: diff against actual project structure. Have new modules, patterns, or conventions emerged since the last update? **Audit Report Format:** ```markdown # Documentation Audit: — ## Summary - Documents audited: N - Complete: N | Accurate: N | Fresh: N - Critical findings: N | Major: N | Minor: N ## Critical Findings 🔴 - ****: — ## Major Findings 🟠 - ****: — ## Minor Findings 🟡 - ****: — ## Recommendations ``` --- ## Common Pitfalls & Anti-Patterns ### ❌ Documentation Anti-Patterns 1. **Writing docs that explain *how* without *why*** — A README that says "Run `npm start`" without explaining what the project does is useless. Lead with purpose, then procedure. 2. **Duplicating information across documents** — The same setup instructions in README.md, CONTRIBUTING.md, and docs/setup.md. Pick one canonical location and link to it from others. 3. **Writing documentation as an afterthought** — "I'll document it after the release." No you won't. Documentation must be part of the definition of done, not a separate task. 4. **Using documentation as a substitute for clean code** — If your code needs 200 lines of docs to explain, the code might be the problem. Documentation supplements clarity; it doesn't replace it. 5. **One-person documentation** — If only one person can maintain the docs, they will rot when that person leaves. Distribute documentation ownership across the team. 6. **Writing for yourself, not your audience** — A README written by the author for the author. Assume the reader knows nothing about your project. Define acronyms. Explain concepts. Provide context. 7. **Screenshots without alt text or descriptions** — Screenshots go stale faster than text. If you use them, describe what they show in alt text so the description survives even when the screenshot doesn't. 8. **Treating ADRs as heavyweight RFCs** — ADRs should be 1-2 pages. If it takes a week to write, it's an RFC, not an ADR. ADRs capture decisions that have already been discussed. RFCs propose decisions for discussion. 9. **Including credentials, tokens, or secrets in documentation** — Even in examples. Use placeholders like `` or env var references. See Safety Rules below. 10. **Neglecting agent-facing documentation** — AI agents are now part of the development team. If your project has conventions, constraints, and patterns that agents should follow, document them in AGENTS.md. ### ✅ Documentation Quality Checklist Before publishing any document, verify: - [ ] The first paragraph answers "what is this and why should I care?" - [ ] Copy-paste-able commands actually work when copy-pasted - [ ] No hardcoded credentials, tokens, or internal IPs - [ ] Links are not broken (test them) - [ ] Code blocks have language specifiers - [ ] File is under 500 lines (split longer docs into multiple files) - [ ] The target audience is clear (new user? API consumer? on-call engineer?) - [ ] Date or version information is present - [ ] Acronyms are expanded on first use - [ ] Cross-references use relative links (within repo) or absolute URLs (external) --- ## Safety Rules **ABSOLUTE RULES — never violate these:** 1. **Never document credentials, secrets, API keys, tokens, or passwords.** Use placeholders: ``, `$DATABASE_URL`, ``. Even in examples. Even in "non-production" contexts. Secrets in docs leak — through copy-paste, screenshots, search indexing, and agent context windows. 2. **Never document internal network details publicly.** Private IPs (`10.x.x.x`, `192.168.x.x`), internal hostnames, and VPN endpoints should not appear in public-facing or widely-shared documentation. 3. **Never include destructive commands without clear warnings.** If a runbook includes `DROP TABLE`, `DELETE FROM`, `TERMINATE`, `rm -rf`, or similar commands, precede them with a ⚠️ warning explaining what they destroy and how to verify you're targeting the right environment. 4. **Never claim documentation is "complete" without an audit.** "Our docs are comprehensive" is a statement of fact, not aspiration. Only make it after running the completeness audit. 5. **Never commit documentation changes without review.** Documentation that describes system behavior is as critical as code that implements it. Review docs with the same rigor as code. 6. **Respect the audience's time.** A 50-page onboarding guide that nobody reads is not documentation — it's a filing exercise. Write for skimming. Put the important information first. Use headers generously. 7. **Agent-facing docs must not contain instructions that violate safety policies.** AGENTS.md and similar files are prompts for AI agents. They must not instruct agents to bypass security, exfiltrate data, or ignore safeguards. --- ## Platform Compatibility Notes This skill is designed to work across AI coding platforms with minor adaptations: | Platform | Notes | |---|---| | **Claude Code** | Can read entire codebase for context. Excellent for auditing and generating comprehensive docs. Use file-reading tools to gather context before writing. | | **Codex (OpenAI)** | Good at generating structured documentation from code. Provide the code context and spec before asking for docs. | | **Cursor** | IDE integration means docs can be generated alongside code. Use CURSOR.md for agent context. | | **Gemini CLI** | Large context window is useful for processing entire codebases at once. Good for documentation audits. | | **OpenClaw** | Access to multiple skills. Combine with api-design-first for API docs, git-workflow-automation for changelogs. | | **GitHub Copilot** | Works best within IDE context. Use `.github/copilot-instructions.md` for agent context. | | **Windsurf** | Can read workspace files natively. Use `.windsurfrules` for agent context. | | **OpenCode** | Terminal-based with full file access. Use AGENTS.md for agent context. | ### Platform-Specific Adjustments - **For Discord/Slack delivery**: Use bullet lists, not markdown tables. Wrap multiple links in `<>` to suppress embeds. Split long docs across multiple messages. - **For API docs**: Prefer generating the OpenAPI spec, not just prose descriptions. The spec is machine-readable and can be rendered by tools. - **For large codebases**: Audit one module at a time. Don't try to document everything in one session. - **If the codebase has no existing docs**: Start with README + AGENTS.md. These are the two highest-leverage documents to create first. - **For diagram generation**: Prefer Mermaid (text-based, version-controllable) over images. Use the diagram-maker skill if complex diagrams are needed. --- ## References - `references/adr-template.md` — Complete ADR template with all sections - `references/markdown-style-guide.md` — Detailed Markdown style guide (loaded on demand) - `references/runbook-template.md` — Runbook template with incident response patterns - `references/api-docs-checklist.md` — API documentation completeness checklist --- ## Verification Checklist Before finalizing any documentation task, confirm: - [ ] The document type is appropriate for the audience and purpose - [ ] The first 3 sentences explain what the document covers and who it's for - [ ] All code blocks have language specifiers and work when copy-pasted - [ ] No credentials, secrets, or internal IPs are exposed - [ ] Links are tested and not broken - [ ] Cross-references use relative links where appropriate - [ ] The document is under 500 lines (or split into multiple files if needed) - [ ] Date or version information is included - [ ] Acronyms are expanded on first use - [ ] Destructive commands in runbooks have ⚠️ warnings - [ ] If this is an agent context file, it does not contain unsafe instructions - [ ] The tone is appropriate for the audience (technical but accessible)