Documentation Patterns

Documentation Patterns

Use this skill when the main problem is document shape and consistency rather than writing quality alone.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Creating a new API, feature, or config guide
• Standardizing Markdown sections across repositories
• Writing migration or runbook documents
• Picking the right template for a doc request

Pattern Selection

• API docs: endpoints, auth, request and response schema, errors
• Feature docs: purpose, UX, dependencies, rollout, support
• Config docs: env vars, defaults, examples, failure modes
• Migration docs: changed behavior, upgrade path, verification

Cross-Skill Workflow

• Use documentation-authoring to gather context and draft the content before template selection becomes the bottleneck.
• Use this skill when structure, section order, or template choice is the main problem.
• Finish with documentation-quality to review the final document against quality expectations.

Agent Prompt Template

Use the documentation-patterns skill to choose and apply the best structure for a [document type].
Context: [feature, system, migration, or runbook].
Bias toward: [API docs, feature docs, config guide, migration guide, etc.].
Return the recommended section outline with short notes on why each section exists.

Shared Documentation Stack

Use this as the inherited baseline for documentation-authoring, documentation-quality, documentation-automation, and documentation-verification.

1. Source of truth: identify owner, audience, canonical files, and freshness requirements before drafting. 2. Structure: choose the smallest reusable pattern that fits the reader task. 3. Verification: check links, commands, examples, screenshots, and version-sensitive claims before publishing. 4. Handoff: state unresolved gaps, owners, and next review trigger instead of implying false completeness.

Anti-Patterns

• Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
• Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
• Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Documentation Patterns output identifies audience, purpose, source of truth, and freshness requirements. 2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill. 3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified. 4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience. 5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

References & Resources

Documentation

• API Documentation Templates - Endpoint, SDK, and function documentation patterns
• Feature Documentation Templates - Feature overview, rollout, and troubleshooting patterns
• Configuration Documentation Templates - Config and environment variable templates

Scripts

• Doc Template Picker - Print a starter Markdown template for api, feature, config, or migration

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:documentation-patterns from this skill. Rebuild commands with python scripts/export-gemini-skill.py documentation-patterns and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Documentation Patterns skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

<!-- MCP:END -->

Related Skills

• documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
• documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
• documentation-verification: Use it when the workflow also needs final documentation validation before publishing.
• notion-docs: Use it when the workflow also needs Notion page and database publishing workflows.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
• Added or referenced the shared documentation-stack approach to reduce duplicated documentation guidance.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

All notable changes to this skill will be documented in this file.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
• Added stronger cross-references to documentation-authoring and documentation-quality, plus a ready-to-copy agent prompt template.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Clarified that the core workflow does not require a dedicated MCP server and can run with local tools alone.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

• Reworked the skill around document-shape selection for API, feature, config, and migration docs

Added

• scripts/doc-template-picker.py to print starter Markdown templates by document type

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

API Documentation Templates

Function Documentation Template

### `functionName(param1, param2)`

Brief description of what the function does.

**Parameters:**
- `param1` (type): Description of parameter
- `param2` (type, optional): Description with default value

**Returns:**
- `type`: Description of return value

**Example:**

const result = functionName('value', 42);

**Throws:**
- `ErrorType`: When and why error is thrown

REST Endpoint Documentation Template

### `HTTP_METHOD /api/endpoint`

Description of what the endpoint does.

**Request:**

{ "param": "value" }

**Response:**

{ "result": "value" }

**Status Codes:**
- 200: Success
- 400: Bad request
- 401: Unauthorized

Configuration Documentation Templates

Environment Variable Template

### `ENV_VAR_NAME`

Description of the environment variable.

**Default:** `default_value`

**Example:**

export ENV_VAR_NAME=value

Config File Structure Template

## Configuration Options

| Option | Type | Default | Description |
|--------|------|----------|-------------|
| `optionName` | type | default | Description |

**Example Configuration:**

optionName: value

Feature Documentation Templates

Feature Documentation Template

## Feature Name

Brief description of the feature.

### Usage

Basic usage example with code snippet.

### Configuration

Configuration options with examples.

### Advanced Usage

Complex scenarios and edge cases.

### Troubleshooting

Common issues and solutions.