documentation-patterns
Technical documentation patterns for READMEs, ADRs, API docs (OpenAPI 3.1), changelogs, and writing style guides. Use when creating project documentation, writing architecture decisions, documenting APIs, or maintaining changelogs.
git clone --depth 1 https://github.com/yonatangross/orchestkit /tmp/documentation-patterns && cp -r /tmp/documentation-patterns/plugins/ork/skills/documentation-patterns ~/.claude/skills/documentation-patternsSKILL.md
# Documentation Patterns Templates and opinionated structures for technical documentation -- READMEs, Architecture Decision Records, OpenAPI specs, changelogs, and writing style. Each category has individual rule files in `rules/` loaded on-demand. ## Quick Reference | Category | Rule | Impact | When to Use | |----------|------|--------|-------------| | [README](#readme) | 1 | HIGH | Starting a project, onboarding contributors | | [ADR](#architecture-decision-records) | 1 | HIGH | Recording architecture decisions | | [API Docs](#api-documentation) | 1 | HIGH | Documenting REST APIs with OpenAPI 3.1 | | [Changelog](#changelog) | 1 | MEDIUM | Maintaining release history | | [Writing Style](#writing-style) | 1 | MEDIUM | Any technical writing task | **Total: 5 rules across 5 categories** ## Quick Start ```markdown ## README Skeleton # Project Name Brief description -> Quick Start -> Installation -> Usage -> API -> Config -> Contributing -> License ## ADR Format # ADR-001: Title Status -> Context -> Decision -> Consequences (positive/negative) -> References ## OpenAPI Minimum openapi: 3.1.0 with info, paths, components/schemas, error responses ## Changelog Entry ## [1.2.0] - 2026-03-05 ### Added / Changed / Deprecated / Removed / Fixed / Security ## Writing Rule of Thumb Active voice, present tense, second person, one idea per sentence ``` ## README Complete README template with all essential sections for open-source and internal projects. - **`docs-readme-structure`** -- Project name, quick start, installation, usage, API reference, configuration, contributing, license ## Architecture Decision Records Structured format for capturing architectural decisions with context and consequences. - **`docs-adr-template`** -- Status, context, decision, consequences (positive/negative), references ## API Documentation OpenAPI 3.1 specification patterns for consistent, machine-readable API docs. - **`docs-api-openapi`** -- Path structure, operation definitions, schema components, error responses (RFC 9457) ## Changelog Keep a Changelog format for curated, human-readable release history. - **`docs-changelog-format`** -- Added, Changed, Deprecated, Removed, Fixed, Security sections with semver ## Writing Style Technical writing conventions for clear, scannable documentation. - **`docs-writing-style`** -- Active voice, present tense, concise sentences, API doc checklist ## Related Skills - `ork:api-design` -- API design patterns (complements OpenAPI documentation) - `ork:architecture-decision-record` -- ADR workflow and lifecycle - `ork:release-management` -- Release process including changelog updates **Version:** 1.0.0 (March 2026)
Accessibility patterns for WCAG 2.2 compliance, keyboard focus management, React Aria component patterns, cognitive inclusion, native HTML-first philosophy, and user preference honoring. Use when implementing screen reader support, keyboard navigation, ARIA patterns, focus traps, accessible component libraries, reduced motion, or cognitive accessibility.
Agent orchestration patterns for agentic loops, multi-agent coordination, alternative frameworks, and multi-scenario workflows. Use when building autonomous agent loops, coordinating multiple agents, evaluating CrewAI/AutoGen/Swarm, or orchestrating complex multi-step scenarios.
AI-assisted UI generation patterns for json-render, v0.app, Google Stitch, Bolt Cloud, and Cursor workflows. Covers prompt engineering for component and full-stack app generation, review checklists for AI-generated code, design token injection, refactoring for design system conformance, and CI gates for quality assurance. Use when generating UI components with AI tools, rendering multi-surface MCP visual output, reviewing AI-generated code, or integrating AI output into design systems.
Queries local analytics across OrchestKit projects for agent usage, skill frequency, hook timing, team activity, session replay, cost estimation, and model delegation trends. Privacy-safe with hashed project IDs. Supports time-range filtering and comparative analysis. Use when reviewing performance, estimating costs, or understanding usage patterns.
Animation and motion design patterns using Motion library (formerly Framer Motion) and View Transitions API. Use when implementing component animations, page transitions, micro-interactions, gesture-driven UIs, or ensuring motion accessibility with prefers-reduced-motion.
API design patterns for REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Use when designing API endpoints, choosing versioning schemes, implementing Problem Details errors, or building OpenAPI specifications.
Use this skill when documenting significant architectural decisions. Provides ADR templates following the Nygard format with sections for context, decision, consequences, and alternatives. Use when writing ADRs, recording decisions, or evaluating options.
Architecture validation and patterns for clean architecture, backend structure enforcement, project structure validation, test standards, and context-aware sizing. Use when designing system boundaries, enforcing layered architecture, validating project structure, defining test standards, or choosing the right architecture tier for project scope.