Skip to content

JPeetz/agent-skills / skills/documentation-content/documentation-and-adrs

documentation-and-adrs

Verified

Use this skill when you need to record an architecture decision (ADR) or document the reasoning behind a design choice — when changing public APIs, shipping features that change behavior, or recording context that future engineers (human or agent) will need to understand the codebase. Does NOT replace code comments or inline docstrings; targets strategic documentation and decision capture. Primary keywords: ADR architecture decision record, technical documentation, design rationale, decision log, API documentation, README writing, changelog, documentation-driven development, inline documentation best practices, specification writing. For all major agentic platforms.

FileKindSize
CHANGELOG.mdmarkdown941 B
LICENSEother1.0 KB
SKILL.mdskill md12.0 KB
evals/evals.jsonconfig5.9 KB
references/adr-template.mdmarkdown2.3 KB
references/api-docs-checklist.mdmarkdown2.0 KB
references/readme-template.mdmarkdown2.1 KB

references/api-docs-checklist.md

View on GitHub
# API Documentation Completeness Checklist

Use this checklist when auditing or writing API documentation. Every check
should be verified — not assumed.

## Every Endpoint

- [ ] HTTP method and path are documented
- [ ] Path parameters documented with types, descriptions, and examples
- [ ] Query parameters documented with types, descriptions, defaults, and whether required
- [ ] Request body schema documented (if applicable) with all field types and descriptions
- [ ] Authentication requirements documented (API key? OAuth? JWT?)
- [ ] Success response shape documented with example
- [ ] Error codes documented — both HTTP status codes and error response body shapes
- [ ] Rate limits documented (requests per window, headers returned)
- [ ] Deprecation status documented if applicable (`Sunset` and `Deprecation` headers)

## Collections (List Endpoints)

- [ ] Pagination method documented (cursor-based vs offset-based)
- [ ] Page size default and maximum documented
- [ ] Sort/filter parameters documented
- [ ] Response includes pagination metadata documented

## Schema / Type Documentation

- [ ] Every field has a description, type, and example
- [ ] Enumerated values are listed with descriptions
- [ ] Required vs optional fields are clearly marked
- [ ] Default values are documented
- [ ] Format constraints documented (ISO 8601 for dates, UUID for IDs, etc.)

## General

- [ ] Base URL is documented
- [ ] API versioning strategy is documented (URL path prefix vs header)
- [ ] Authentication/authorization flow is documented end to end
- [ ] Error response shape is consistent across all endpoints (RFC 7807 recommended)
- [ ] Example requests and responses exist for all major use cases
- [ ] Rate limit headers and retry-after behavior documented
- [ ] Changelog or version history for the API exists
- [ ] Contact/support information for API consumers
- [ ] SDK or client library links (if available)
- [ ] OpenAPI spec is the canonical source — human docs are generated from it, not maintained separately
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall