git:20260712.306b1bd to git:20260803.0223e2b

5 added, 5 removed. Audit A to A.

---

name: technical-documentation

- description: Create and review technical documentation, including READMEs, agent-facing instructions, API references, and CLI help. Use when documentation must help someone complete real work.

+ description: Create and review technical documentation, including READMEs, agent-facing instructions, API references, and CLI help. Use when documentation must help someone complete real work. Do not use for marketing copy, brand messaging, or long-form editorial content.

license: MIT

compatibility: No runtime dependency.

metadata:

source_repo: https://github.com/magnus919/hermes-profiles

source_commit: 867a555

---

# Technical Documentation Methodology

Technical documentation is the interface between a tool and its user. This methodology covers writing documentation that answers the reader's question, doesn't get in their way, and stays maintainable as the project evolves.

## The Technical Writer's Domain

| You own | You don't own |

|---------|--------------|

- | API documentation — endpoint references, parameters, examples | Editorial and long-form narrative content — that's the writer |

+ | API documentation — endpoint references, parameters, examples | Editorial and long-form narrative content — owned by the editorial function, outside this skill's scope |

| README authorship — project overview, quickstart, configuration | Brand messaging and marketing copy — that's the brand designer |

- | CLI documentation — help text, usage patterns, exit codes | Code architecture decisions — those belong to the technical architect |

+ | CLI documentation — help text, usage patterns, exit codes | Code architecture decisions — that's the software-architecture-analysis |

| Agent-facing docs — AGENTS.md, skill documentation | Project roadmap and product vision — that's the product manager |

- | Reference documentation — config files, troubleshooting, architecture | Performance optimization guidance — that's the debugger/SRE |

- | Documentation site structure — IA, cross-referencing, search | Code quality and standards — that's the reviewer/QA engineer |

+ | Reference documentation — config files, troubleshooting, architecture | Performance optimization guidance — that's the systematic-debugging / SRE |

+ | Documentation site structure — IA, cross-referencing, search | Code quality and standards — that's the qa-methodology / QA engineer |

## Reference Files

| Reference | When to load |

|-----------|-------------|

| `references/readme-patterns.md` | Writing or restructuring a README — sections every README needs, quickstart patterns, installation variants, configuration documentation |

| `references/api-documentation-cli-help.md` | Documenting APIs (endpoint structure, parameter conventions, example design, auth patterns, OpenAPI annotations) and designing CLI help text (usage line, flags, exit codes, subcommand hierarchy, man pages) |

| `references/agent-facing-docs.md` | Writing AGENTS.md and skill documentation — trigger patterns, loading order, output contracts, cross-references |

| `references/information-architecture.md` | Structuring a documentation site — progressive disclosure, cross-referencing, search optimization, maintenance strategy |

## Core Principles

**Document the interface, not the implementation** — Users need to know what a function does, what it expects, and what it returns. How it works internally is for the source code.

**Good docs answer the question the reader has** — Different readers come with different questions. Getting started? Reference? Troubleshooting? Structure docs to route each reader to their answer fast.

**Exhaustive completeness over narrative arc** — Technical docs are not articles. Readers skip to the part they need. Cover every parameter, every edge case, every error code. Don't skip the boring bits — those are the ones people need.

**Every doc is a liability** — Every page you write must be maintained. Prefer documenting less with more completeness over documenting everything with lower quality. Maintenance cost is proportional to surface area.

**Show, don't just tell** — Every concept needs a worked example. Every API endpoint needs a request and response. Every configuration option needs a complete example, not just a description.

## Portability

This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.