Provides standards for essential project documentation including READMEs and ADRs.
Install
mkdir -p .claude/skills/docs-zircote-plugins && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/17304" && unzip -o skill.zip -d .claude/skills/docs-zircote-plugins && rm skill.zipInstalls to .claude/skills/docs-zircote-plugins
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
This skill should be used when the user asks about "documentation", "README", "CHANGELOG", "CONTRIBUTING", "ADR", "architecture decision record", "changelog format", "keep a changelog", "doc comments", "API documentation", or needs guidance on project documentation requirements.Key capabilities
- →Define mandatory documentation files like README, CHANGELOG, LICENSE
- →Specify required sections for README files
- →Enforce Keep a Changelog format and version entry structure
- →Outline required sections for CONTRIBUTING.md
- →Detail when and how to create Architecture Decision Records (ADRs)
- →Specify ADR location, required sections, and naming conventions
How it works
The skill provides standards for project documentation, including mandatory files, required sections for READMEs and CONTRIBUTING.md, and specific formatting for Changelogs and Architecture Decision Records. It also outlines ADR creation guidelines.
Inputs & outputs
When to use docs
- →Creating ADRs
- →Updating project documentation
- →Structuring README files
About this skill
Documentation Standards
Guidance for implementing documentation requirements including project docs, changelogs, and Architecture Decision Records.
Tooling
Available Tools: If using Claude Code, the
documentation-reviewplugin provides comprehensive documentation tools (/doc-review,/doc-create,/doc-update,/changelog). For ADRs, use theadrplugin (/adr:new,/adr:list,/adr:search).
Required Documentation
Mandatory Files (MUST)
| Document | Purpose |
|---|---|
README.md | Project overview, quick start, installation |
CONTRIBUTING.md | Contributor guidelines, setup instructions |
CHANGELOG.md | Version history and change documentation |
LICENSE | Software license terms |
SECURITY.md | Security policy and vulnerability reporting |
Recommended Files (SHOULD)
| Document | Purpose |
|---|---|
CODE_OF_CONDUCT.md | Community standards |
docs/architecture.md | System design and decisions |
| API documentation | Generated from code comments |
README Requirements
Required Sections (MUST)
README MUST include:
- Project name and brief description
- Badge indicators (CI status, version, coverage, license)
- Installation instructions (multiple methods if applicable)
- Quick start/usage examples
- Links to detailed documentation
- License information
- Contribution link
Recommended Sections (SHOULD)
README SHOULD include:
- Feature list with descriptions
- Architecture overview (diagram recommended)
- Performance characteristics
- Configuration options
- Troubleshooting section
Badge Examples
[](...)
[](...)
[](...)
[](...)
Changelog Requirements
Format (MUST)
Changelogs MUST follow the Keep a Changelog format.
Version Entry Structure (MUST)
Each version entry MUST be organized into these categories:
| Category | Purpose |
|---|---|
| Added | New features |
| Changed | Changes to existing functionality |
| Deprecated | Features to be removed |
| Removed | Removed features |
| Fixed | Bug fixes |
| Security | Security-related changes |
Required Elements (MUST)
Changelogs MUST include:
- Version number
- Release date
- Comparison links to previous versions
Unreleased Section (MUST)
The [Unreleased] section MUST be maintained for ongoing changes.
Changelog Template
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- New feature description
## [1.0.0] - 2024-01-15
### Added
- Initial release features
### Fixed
- Bug fix description
[Unreleased]: https://github.com/org/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0
Contributing Guidelines
Required Sections (MUST)
CONTRIBUTING.md MUST include:
- Prerequisites and tool requirements
- Development environment setup steps
- Build and test instructions
- Code style guidelines
- Pull request process
- Commit message format
Recommended Sections (SHOULD)
CONTRIBUTING.md SHOULD include:
- Project structure overview
- Troubleshooting section
- Contact/support information
Architecture Decision Records (ADRs)
When to Create (MUST)
Significant technical decisions MUST be documented as ADRs.
Location (MUST)
ADRs MUST be stored in version control at docs/adrs/ (or docs/decisions/).
Required Sections (MUST)
Each ADR MUST include:
| Section | Content |
|---|---|
| Title | Descriptive title with ADR number |
| Status | Proposed, Accepted, Deprecated, Superseded |
| Context | Background and problem statement |
| Decision | The chosen approach |
| Consequences | Positive and negative outcomes |
Recommended Sections (SHOULD)
ADRs SHOULD also include:
- Decision drivers (weighted criteria)
- Considered alternatives
- Implementation notes
- Related ADRs
ADR Format (MUST)
ADRs MUST use a structured format such as:
- Structured MADR (recommended)
- MADR (Markdown Architectural Decision Records)
- Nygard format
- Y-Statement format
ADR Naming (MUST)
ADR files MUST use consistent naming: adr_NNNN.md or NNNN-title.md.
ADR Index (MUST)
Projects MUST maintain an ADR index/README listing all decisions.
Implementation Checklist
- Create README.md with required sections
- Create CONTRIBUTING.md
- Create CHANGELOG.md with proper format
- Add LICENSE file
- Create SECURITY.md
- Set up docs/adrs/ directory
- Create ADR template
- Create ADR index/README
Compliance Verification
# Verify required docs exist
ls README.md CONTRIBUTING.md CHANGELOG.md LICENSE SECURITY.md
# Check README has badges
grep -E "^\[!\[" README.md
# Verify changelog format
grep -E "^\## \[" CHANGELOG.md
# Check ADR directory
ls docs/adrs/ || ls docs/decisions/
Additional Resources
Reference Files
references/readme-template.md- Complete README templatereferences/adr-template.md- MADR ADR template
Examples
examples/CHANGELOG.md- Example changelogexamples/CONTRIBUTING.md- Example contributing guideexamples/adr-0001.md- Example ADR
When not to use it
- →When the user is not asking about documentation, changelogs, or ADRs
- →When the task is not related to project documentation requirements
Limitations
- →Does not directly generate documentation content
- →Does not provide real-time validation of documentation compliance
How it compares
This skill standardizes project documentation by providing clear requirements and templates for various document types, ensuring consistency and completeness across projects more effectively than unguided documentation efforts.
Compared to similar skills
docs side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| docs (this skill) | 0 | 5mo | Review | Beginner |
| architecture-decision-records | 54 | 4mo | Review | Beginner |
| meeting-minutes | 41 | 5mo | No flags | Beginner |
| docs-write | 22 | 5mo | No flags | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by zircote-plugins
View all by zircote-plugins →You might also like
architecture-decision-records
wshobson
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
meeting-minutes
github
Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.
docs-write
metabase
Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).
rust-docs-guidelines
RediSearch
Guidelines for writing Rust documentation
ml-paper-writing
davila7
Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.
content-research-writer
ComposioHQ
Assists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership.