* feat(skill): cross-pollinate the new tool wave into catalog routing Wire the recent tool skill wave into the two-layer routing graph so the new tool skills are reachable from the methodology skills that own their domains, and vice versa: - methodology -> tool down-routes: platform-engineering -> kubernetes, terraform, telemetry, postgres, grafana; site-reliability-engineering -> telemetry, grafana; data-engineering and backend-engineering -> postgres; frontend-engineering -> mobile-development; verification-methodology -> playwright, documents; technical-documentation -> documents - neckbeard: add mobile-development and documents routing rows plus change-surface coverage entries, and cross-link the lightweight test-hardening path to qa-methodology's bounded mutation-review material - collaboration layer: chief-of-staff-methodology -> slack/notion/email, go-to-market -> crm, conditional-customer-success -> crm; fix the dead seo-content-optimization reference in go-to-market (now seo-audit) - references/skill-triggers.md: add trigger rows for the 14 new skills - bring go-to-market's description up to the quality validator's imperative-verb + negative-boundary requirement and regenerate catalogs Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * fix(skill): add eval manifest for technical-documentation The eval-coverage ratchet fails on modified skills without a schema-valid manifest once coverage passes 50%. technical-documentation was modified by the routing cross-pollination change and lacked one; add six output-quality cases covering README authorship, API reference generation, CLI help design, agent-facing docs, documentation-site IA, and troubleshooting sections. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
3.9 KiB
name, description, license, compatibility, metadata
| name | description | license | compatibility | metadata | ||||
|---|---|---|---|---|---|---|---|---|
| technical-documentation | 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. | MIT | No runtime dependency. |
|
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 — 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 — 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 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 |
Related Skills
- documents — producing office-format deliverables (PDF, Word, Excel, PowerPoint) from documentation content; doc-site and markup conventions stay here.
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.