akaszubski/documentation-guide
plugins/autonomous-dev/skills/documentation-guide/SKILL.md
Documentation standards enforcing Keep a Changelog format, README structure, ADR templates, and Google-style docstrings. Use when writing CHANGELOG entries, updating READMEs, or documenting APIs. TRIGGER when: changelog, readme, documentation, docstring, ADR, API docs. DO NOT TRIGGER when: code-only changes, test files, config updates without API changes.
$ install --global
skillsauthnpx skillsauth add akaszubski/autonomous-dev documentation-guideInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 3, 2026, 8:43 AM5.3s1 file scanned
SKILL.md
- name:
- documentation-guide
- description:
- Documentation standards enforcing Keep a Changelog format, README structure, ADR templates, and Google-style docstrings. Use when writing CHANGELOG entries, updating READMEs, or documenting APIs. TRIGGER when: changelog, readme, documentation, docstring, ADR, API docs. DO NOT TRIGGER when: code-only changes, test files, config updates without API changes.
- allowed-tools:
- [Read, Write, Edit, Grep, Glob]
Documentation Guide Enforcement Skill
Ensures all documentation is consistent, current, and complete. Used by the doc-master agent.
Keep a Changelog Format
All CHANGELOG entries MUST follow Keep a Changelog format.
Categories (in this order)
- Added — new features
- Changed — changes to existing functionality
- Deprecated — soon-to-be removed features
- Removed — removed features
- Fixed — bug fixes
- Security — vulnerability fixes
Structure
# Changelog
## [Unreleased]
### Added
- New authentication module (#123)
### Fixed
- Token expiry off-by-one error (#124)
## [1.2.0] - 2026-02-15
### Added
- Batch processing support (#100)
The [Unreleased] section MUST always exist at the top for accumulating changes.
README Required Sections
Every README.md MUST contain these sections in order:
- Overview — 1-2 sentence project description
- Installation — How to install/set up
- Usage / Quick Start — Minimal working example
- Commands Table — Available commands with descriptions
- Configuration — Config files, env vars, options
- Contributing — How to contribute, link to CONTRIBUTING.md
Docstring Format: Google Style
All public functions MUST have Google-style docstrings.
def process_data(
data: List[Dict],
*,
validate: bool = True,
) -> ProcessResult:
"""Process input data with optional validation.
Args:
data: Input records as list of dicts with 'id' and 'content' keys.
validate: Whether to validate input before processing.
Returns:
ProcessResult with metrics and processed items.
Raises:
ValueError: If data is empty or missing required keys.
"""
Include Args, Returns, and Raises for every public function. Omit sections only if truly not applicable (e.g., no exceptions raised).
HARD GATE: Sync Rules
Documentation MUST stay in sync with code at all times.
FORBIDDEN:
- Updating code without updating corresponding docs
- Hardcoded component counts (e.g., "17 agents") — use dynamic discovery or verify against filesystem
- Undocumented public APIs — every public function needs a docstring
- Stale cross-references — links to files/sections that no longer exist
- CHANGELOG entries without issue/PR numbers
- Version dates that do not match actual release dates
REQUIRED:
- CHANGELOG entry for every user-visible change
- Version date updated when changes are made
- Component counts verified against filesystem before committing
- Cross-references validated (all linked files exist)
- README updated when commands or configuration change
- Docstrings updated when function signatures change
When to Update Which Docs
| Change Type | README | CHANGELOG | Docstrings | ADR | |------------|--------|-----------|------------|-----| | API change | Yes | Yes | Yes | Maybe | | New feature | Yes | Yes | Yes | Maybe | | Bug fix | No | Yes | No | No | | Refactor (no behavior change) | No | No | Maybe | Maybe | | Architecture decision | No | No | No | Yes | | Config change | Yes | Yes | No | No | | Deprecation | Yes | Yes | Yes | Maybe |
ADR Template
For major architectural decisions, create an ADR (Architecture Decision Record).
# ADR-NNN: [Title]
**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-NNN
## Context
What is the issue or decision we need to make?
## Decision
What did we decide and why?
## Consequences
What are the positive and negative outcomes?
## Alternatives Considered
What other options were evaluated and why were they rejected?
Store ADRs in docs/adr/ directory, numbered sequentially.
Anti-Patterns
BAD: Hardcoded counts
This project has 17 agents and 40 skills.
These numbers drift immediately. Verify against filesystem or use dynamic discovery.
GOOD: Verified counts
# Count before documenting
ls plugins/autonomous-dev/agents/*.md | wc -l
ls plugins/autonomous-dev/skills/*/SKILL.md | wc -l
BAD: Stale cross-references
See [architecture guide](docs/ARCHITECTURE.md) for details.
If docs/ARCHITECTURE.md was renamed to docs/ARCHITECTURE-OVERVIEW.md, this link is broken.
GOOD: Validated references
Check all links exist before committing documentation changes.
BAD: Missing CHANGELOG entry
Shipping a user-visible feature with no CHANGELOG entry. Users cannot discover what changed.
GOOD: CHANGELOG-first workflow
Write the CHANGELOG entry before or during implementation, not as an afterthought.
Cross-References
- git-github: Commit message and PR conventions
- code-review: Documentation checklist item (#8)
Related Skills
akaszubski/content-allocation
development
VerifiedTrustedCommunity
One topic, one home. Routes content to its canonical store (CLAUDE.md, PROJECT.md, MEMORY.md, docs/, memory/) and audits for duplication. TRIGGER when: auditing CLAUDE.md/PROJECT.md/MEMORY.md sizes, deduplicating docs, applying the content-allocation pattern to a new repo, running /align --content. DO NOT TRIGGER when: implementing features, writing tests, routine code edits, debugging.
28SKILL.mdUpdated May 28, 2026
akaszubski/testing-guide
development
VerifiedTrustedCommunity
GenAI-first testing with structural assertions, congruence validation, and tier-based test structure. Use when writing tests, setting up test infrastructure, or validating coverage. TRIGGER when: test, pytest, coverage, TDD, test patterns, congruence, validation. DO NOT TRIGGER when: production code implementation, documentation, config-only changes.
28SKILL.mdUpdated Apr 3, 2026
akaszubski/prompt-engineering
testing
VerifiedTrustedCommunity
Prompt engineering patterns for writing agent prompts and skill files — constraint budgets, register shifting, HARD GATE patterns, anti-personas. Use when writing or reviewing agents/*.md or skills/*/SKILL.md. TRIGGER when: agent prompt, skill file, prompt engineering, model-tier compensation, HARD GATE, prompt quality. DO NOT TRIGGER when: user-facing docs, README, CHANGELOG, config files.
21SKILL.mdUpdated Apr 15, 2026
akaszubski/planning-workflow
testing
VerifiedTrustedCommunity
7-step planning workflow for pre-implementation design. Enforced by plan_gate hook, critiqued by plan-critic agent. Use when creating plans, design documents, or architecture decisions before implementation. TRIGGER when: plan, planning, /plan, design document, architecture decision. DO NOT TRIGGER when: implementation, coding, testing.
21SKILL.mdUpdated Apr 15, 2026