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.
- Source of truth: identify owner, audience, canonical files, and freshness requirements before drafting.
- Structure: choose the smallest reusable pattern that fits the reader task.
- Verification: check links, commands, examples, screenshots, and version-sensitive claims before publishing.
- Handoff: state unresolved gaps, owners, and next review trigger instead of implying false completeness.
Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
$CODEX_HOME/skills/documentation-patterns and restart Codex after major changes.
MCP Availability And Fallback
Preferred MCP Server: None required
- Fallback prompt: "Use the Documentation Patterns skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
- Do not claim an MCP operation was used when the active host does not expose it.
- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
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":
- Pass/fail: The Documentation Patterns output identifies audience, purpose, source of truth, and freshness requirements.
- Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
- Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
- Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
- Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
References & Resources
Documentation
Scripts
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.
1---
2name: documentation-patterns
3version: "2.0"
4last_updated: 2026-09-08
5tags: [documentation, patterns, docs, writing, quality]
6description: "Templates and structural patterns for API docs, feature docs, config guides, and REST endpoint documentation. Use when structuring docs, applying Markdown templates, or standardizing doc formats."
7metadata:
8 source: https://skillmd.com/skills/practicalswan/documentation-patterns
9---
10
11# Documentation Patterns
12
13Use this skill when the main problem is document shape and consistency rather than writing quality alone.
14
15- Leverage native parallel subagent dispatch and 200k+ context windows where available.
16
17
18## Activation Conditions
19
20Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
21
22- Creating a new API, feature, or config guide
23- Standardizing Markdown sections across repositories
24- Writing migration or runbook documents
25- Picking the right template for a doc request
26
27## Pattern Selection
28
29- API docs: endpoints, auth, request and response schema, errors
30- Feature docs: purpose, UX, dependencies, rollout, support
31- Config docs: env vars, defaults, examples, failure modes
32- Migration docs: changed behavior, upgrade path, verification
33
34## Cross-Skill Workflow
35
36- Use [documentation-authoring](../documentation-authoring/SKILL.md) to gather context and draft the content before template selection becomes the bottleneck.
37- Use this skill when structure, section order, or template choice is the main problem.
38- Finish with [documentation-quality](../documentation-quality/SKILL.md) to review the final document against quality expectations.
39
40## Agent Prompt Template
41
42```text
43Use the documentation-patterns skill to choose and apply the best structure for a [document type].
44Context: [feature, system, migration, or runbook].
45Bias toward: [API docs, feature docs, config guide, migration guide, etc.].
46Return the recommended section outline with short notes on why each section exists.
47```
48
49## Shared Documentation Stack
50
51Use this as the inherited baseline for documentation-authoring, documentation-quality, documentation-automation, and documentation-verification.
52
531. Source of truth: identify owner, audience, canonical files, and freshness requirements before drafting.
542. Structure: choose the smallest reusable pattern that fits the reader task.
553. Verification: check links, commands, examples, screenshots, and version-sensitive claims before publishing.
564. Handoff: state unresolved gaps, owners, and next review trigger instead of implying false completeness.
57
58<!-- MCP:START -->
59
60<!-- PORTABILITY:START -->
61## Cross-Client Portability
62
63This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.
64
65- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
66 workflow in project instructions when folder discovery is unavailable.
67- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
68- Codex: install or sync the folder into
69 `$CODEX_HOME/skills/documentation-patterns` and restart Codex after major changes.
70
71<!-- PORTABILITY:END -->
72
73## MCP Availability And Fallback
74
75Preferred MCP Server: None required
76
77- Fallback prompt: "Use the Documentation Patterns skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
78- Do not claim an MCP operation was used when the active host does not expose it.
79- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.
80
81<!-- MCP:END -->
82
83## Anti-Patterns
84
85- Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
86- Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
87- Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.
88
89## Verification Protocol
90
91Before claiming "skill applied successfully":
92
931. Pass/fail: The Documentation Patterns output identifies audience, purpose, source of truth, and freshness requirements.
942. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill.
953. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified.
964. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience.
975. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.
98
99## References & Resources
100
101### Documentation
102- [API Documentation Templates](./references/api-templates.md) - Endpoint, SDK, and function documentation patterns
103- [Feature Documentation Templates](./references/feature-templates.md) - Feature overview, rollout, and troubleshooting patterns
104- [Configuration Documentation Templates](./references/config-templates.md) - Config and environment variable templates
105
106### Scripts
107- [Doc Template Picker](./scripts/doc-template-picker.py) - Print a starter Markdown template for `api`, `feature`, `config`, or `migration`
108
109## Related Skills
110
111- [documentation-authoring](../documentation-authoring/SKILL.md): Use it when the workflow also needs drafting structured technical or product documents.
112- [documentation-quality](../documentation-quality/SKILL.md): Use it when the workflow also needs documentation review standards and quality gates.
113- [documentation-verification](../documentation-verification/SKILL.md): Use it when the workflow also needs final documentation validation before publishing.
114- [notion-docs](../notion-docs/SKILL.md): Use it when the workflow also needs Notion page and database publishing workflows.