readme-writing_skill

Overview

This skill teaches how to write concise folder-level documentation that explains why a directory exists and how its contents are organized. It focuses on conveying purpose, mental models, and cross-folder relationships so contributors know where to add or find code. The goal is scannable, practical context rather than duplicating file lists.

How this skill works

It inspects a directory and helps craft a short documentation file that explains intent, organizational logic, and non-obvious decisions. It recommends what context to include: purpose, conventions, boundaries, and links to related areas. It avoids repeating filenames or code that are already visible.

When to use it

• When adding a new directory to a project and you want to explain its role
• When reorganizing code so other contributors understand the new structure
• When onboarding teammates who need the mental model for where things live
• When a folder has conventions or interactions with other parts of the codebase
• When documentation is needed but should stay brief and targeted

Best practices

• Start with a one-line purpose statement describing why the folder exists
• Explain the organizational logic and mental model, not the file list
• Note any conventions, expected file types, and where to add new code
• Mention relationships to other folders or services when relevant
• Keep it short and scannable—few sentences or a short paragraph is usually enough
• Reserve full setup/usage instructions for project-level documentation

Example use cases

• A converters folder: explain that each module transforms a field schema into format-specific output and where to add a new converter
• A feature subfolder: describe the feature boundary, props passed from parent, and expected side effects
• A shared components folder: specify design system rules, export patterns, and styling conventions
• A platform adapter folder: clarify which runtime it targets and how it integrates with core logic
• An examples folder: state the intent (small demos), expected audience, and how to run them