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.
You Might Also Like
Related Skills
update-docs
This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.
vercel
docstring
Write docstrings for PyTorch functions and methods following PyTorch conventions. Use when writing or updating docstrings in PyTorch code.
pytorch
docs-writer
Always use this skill when the task involves writing, reviewing, or editing files in the `/docs` directory or any `.md` files in the repository.
google-gemini
write-concept
Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines
leonardomsoresource-curator
Find, evaluate, and maintain high-quality external resources for JavaScript concept documentation, including auditing for broken and outdated links
leonardomso
doc-coauthoring
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
anthropics