Skip to content

JPeetz/agent-skills / skills/documentation-content/technical-documentation

technical-documentation

Verified

Use 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.

FileKindSize
CHANGELOG.mdmarkdown2.3 KB
LICENSEother1.0 KB
SKILL.mdskill md29.9 KB
evals/evals.jsonconfig5.0 KB
references/adr-template.mdmarkdown2.5 KB
references/api-docs-checklist.mdmarkdown5.6 KB
references/markdown-style-guide.mdmarkdown5.4 KB
references/runbook-template.mdmarkdown6.0 KB
scripts/validate_skill.pyexecutablescript12.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.*
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall