When should I create an Architecture Decision Record (ADR)?

An ADR should be created whenever you make a significant architectural choice that will impact the project long-term, providing context and consequences for future developers.

How does this skill improve README files?

It provides a minimal, effective structure that prioritizes 'Quick Start' and 'Setup' sections, ensuring users can find the fastest path to running the project.

What is the 'Why Not What' principle?

It is the philosophy that code should be written clearly enough to explain what it is doing, while comments should be reserved for explaining the reasoning, trade-offs, and decisions behind the code.

Does this skill support automated documentation tools?

Yes, it includes guidance for using Lychee for fast link checking and Vale for enforcing prose style guides like Google or Microsoft standards.

Documentation Standards

Name: Documentation Standards
Author: phrazzld

byphrazzld

•

学習とドキュメンテーション

Enforces best practices for technical documentation by prioritizing code clarity and explaining the reasoning behind implementation decisions.

This skill provides a comprehensive framework for maintaining high-quality software documentation, focusing on the 'why not what' principle to ensure comments add value beyond the code itself. It guides users through creating effective README files, Architecture Decision Records (ADRs), and automated documentation maintenance workflows using tools like Vale and Lychee. By encouraging minimal yet impactful documentation, this skill helps development teams reduce technical debt and maintain a clear, reliable source of truth for their projects across the entire software development lifecycle.

主な機能

01Provides criteria for when to update or delete stale documentation

02Optimizes public API contracts and code comment density

03Applies the 'Why Not What' commenting principle for clearer intent

042 GitHub stars

05Standardizes README.md, ADR, and ARCHITECTURE.md structures

06Guides automated link checking and style linting integration

ユースケース

01Setting up comprehensive documentation for a new open-source project

02Automating documentation quality checks within a CI/CD pipeline

03Reviewing pull requests to ensure comments explain logic rather than restating code

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add phrazzld/claude-config documentation-standards

For use in Claude.ai and ChatGPT

Download Skill