readme-writing
Guidelines for writing folder READMEs. Use when creating README.md files for directories.
When & Why to Use This Skill
This Claude skill provides expert guidelines for crafting meaningful folder-level READMEs. It shifts the focus from redundant file listings to explaining the 'why' behind directory structures, helping developers document the mental models and organizational logic of their codebases for better maintainability and team alignment.
Use Cases
- Onboarding New Developers: Quickly explain the purpose and architecture of complex directories to reduce the learning curve for new team members.
- Standardizing Technical Documentation: Implement a consistent documentation style across large-scale projects to ensure every folder provides actionable context.
- Architectural Clarity: Use the guidelines to document the reasoning behind specific design patterns and where new code components should reside.
- Codebase Maintenance: Improve long-term project health by ensuring that the intent of the folder structure is preserved as the project evolves.
| name | readme-writing |
|---|---|
| description | Guidelines for writing folder READMEs. Use when creating README.md files for directories. |
README Writing
A folder README has one job: explain why this folder exists.
Users can run ls to see what's in a folder. They need you to explain the reasoning behind the organization, the mental model, and any non-obvious context that helps them understand where things belong.
Good README
Explains purpose, organizational logic, and helpful context:
# Converters
Transform field schemas into format-specific representations.
Field schemas are pure JSON Schema objects with `x-component` hints. Different systems need them in different formats: ArkType for runtime validation, Drizzle for SQLite column definitions.
Each converter takes the same input (a field schema) and produces output for a specific consumer. If you need field schemas in a new format, add a converter here.
Bad README
File listing that duplicates what's visible:
# Converters
- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports
Guidelines
- Explain the "why" and the mental model
- Add context that helps developers know where to put new code
- Mention relationships to other folders when relevant
- Don't list files or duplicate what's obvious from the code
- Keep it scannable; a few sentences to a short paragraph is usually enough
Exception: Root project READMEs need installation, usage, etc. This skill is for internal folder documentation.