home / skills / epicenterhq / epicenter / readme-writing

readme-writing skill

safe

/skills/readme-writing

This skill helps write folder READMEs by explaining why the folder exists, its mental model, and how to place future code within the structure.

npx playbooks add skill epicenterhq/epicenter --skill readme-writing

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
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:

```markdown
# 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:

```markdown
# 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.

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

FAQ

Should I list every file in the folder?

No. File listings duplicate what is visible; instead explain why the folder exists and how it is organized.

How long should the file be?

Generally a few sentences to a short paragraph. Only project-root documentation needs detailed install and usage sections.