documentation-patterns

Name: documentation-patterns
Author: yonatangross/orchestkit

$npx mdskill add yonatangross/orchestkit/documentation-patterns

Provides templates and structures for technical documentation like READMEs, ADRs, and OpenAPI specs.

Helps create project documentation, record architecture decisions, and maintain changelogs.
Integrates with tools like Read, Glob, and Grep for on-demand rule loading.
Uses opinionated patterns and categories to recommend documentation formats.
Presents results through rule files and quick reference tables for easy access.

SKILL.md

.github/skills/documentation-patternsView on GitHub ↗

---
name: documentation-patterns
license: MIT
compatibility: "Claude Code 2.1.76+."
description: 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.
tags: [documentation, readme, adr, api-docs, openapi, changelog, writing-style, technical-writing]
version: 1.0.0
author: OrchestKit
user-invocable: false
disable-model-invocation: true
context: inherit
complexity: low
persuasion-type: reference
effort: low
allowed-tools:
  - Read
  - Glob
  - Grep
---

# 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)

More from yonatangross/orchestkit

Skill	Description
agent-orchestration	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-ui-generation	AI-assisted UI generation patterns for json-render, v0, Bolt, and Cursor workflows. Covers prompt engineering for component 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.
analytics	Query cross-project usage analytics. Use when reviewing agent, skill, hook, or team performance across OrchestKit projects. Also replay sessions, estimate costs, and view model delegation trends.
animation-motion-design	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.
architecture-patterns	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.
ascii-visualizer	ASCII diagram patterns for architecture, workflows, file trees, and data visualizations. Use when creating terminal-rendered diagrams, box-drawing layouts, progress bars, swimlanes, or blast radius visualizations.
assess	Assesses and rates quality 0-10 with pros/cons analysis. Use when evaluating code, designs, or approaches.
async-jobs	Async job processing patterns for background tasks, Celery workflows, task scheduling, retry strategies, and distributed task execution. Use when implementing background job processing, task queues, or scheduled task systems.
audit-full	Full-codebase audit using 1M context window. Security, architecture, and dependency analysis in a single pass. Use when you need whole-project analysis.
audit-skills	Audits all OrchestKit skills for quality, completeness, and compliance with authoring standards. Use when checking skill health, before releases, or after bulk skill edits to surface SKILL.md files that are too long, have missing frontmatter, lack rules/references, or are unregistered in manifests.