JPeetz/agent-skills / skills/documentation-content/technical-documentation
technical-documentation
VerifiedUse this skill when creating, maintaining, or auditing technical documentation — READMEs, ADRs, API docs, runbooks, onboarding guides, changelogs, knowledge bases, and AI agent context files (AGENTS.md/CLAUDE.md). Covers documentation- driven development, OpenAPI generation, markdown best practices, and completeness/accuracy audits. For all major agentic platforms.
| File | Kind | Size |
|---|---|---|
| CHANGELOG.md | markdown | 2.3 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 29.9 KB |
| evals/evals.json | config | 5.0 KB |
| references/adr-template.md | markdown | 2.5 KB |
| references/api-docs-checklist.md | markdown | 5.6 KB |
| references/markdown-style-guide.md | markdown | 5.4 KB |
| references/runbook-template.md | markdown | 6.0 KB |
| scripts/validate_skill.pyexecutable | script | 12.3 KB |
references/adr-template.md
View on GitHub# ADR-NNNN: [Short Title of Decision]
- **Status**: [proposed | accepted | rejected | deprecated | superseded by [ADR-NNNN](NNNN-link.md)]
- **Date**: YYYY-MM-DD
- **Deciders**: [list of people involved in the decision]
- **Technical Story**: [ticket/issue URL or description of the problem]
---
## Context and Problem Statement
[Describe the context and problem statement in 2-3 paragraphs. What forces
are at play? What constraints exist? What triggered this decision now and
not earlier or later? What is the concrete problem we're solving?]
## Decision Drivers
- [driver 1, e.g., scalability requirement]
- [driver 2, e.g., team expertise with technology]
- [driver 3, e.g., cost constraint]
- [driver 4, e.g., time-to-market pressure]
- [driver 5, e.g., compliance/regulatory requirement]
## Considered Options
### Option 1: [Name]
[Detailed description of option 1. Include enough detail that someone who
joins the team in 2 years can understand what this option entailed.]
**Pros:**
- [pro 1]
- [pro 2]
- [pro 3]
**Cons:**
- [con 1]
- [con 2]
- [con 3]
### Option 2: [Name]
[Detailed description of option 2.]
**Pros:**
- [pro 1]
- [pro 2]
**Cons:**
- [con 1]
- [con 2]
### Option 3: [Name]
[Detailed description of option 3. Include "do nothing" or "status quo" as
an option when applicable — it's often surprisingly viable.]
**Pros:**
- [pro 1]
**Cons:**
- [con 1]
## Decision Outcome
**Chosen option**: "[Option X — Name]", because [summary of the key reason
in one sentence].
### Positive Consequences
- [e.g., improvement in X metric, reduced complexity, team alignment]
- [e.g., enables future Y capability]
### Negative Consequences
- [e.g., increased operational overhead for Z]
- [e.g., learning curve for team members unfamiliar with the technology]
- [e.g., migration cost from existing system]
### Mitigations
- For [negative consequence 1]: [how we'll mitigate it]
- For [negative consequence 2]: [how we'll mitigate it]
## Implementation Plan
1. [Step 1 — who, what, by when]
2. [Step 2 — who, what, by when]
3. [Step 3 — who, what, by when]
4. [Validation: how will we know the decision was correct?]
## Links
- [Link to relevant documentation, RFC, or external resource]
- [Link to related ADRs]
- [Link to the PR or issue where this was discussed]
---
*Template based on [Michael Nygard's ADR format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
with extensions for implementation planning and mitigation tracking.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |