readme-writing
编写文件夹README指南。在创建README.md文件时使用。
📖 中文导读:编写文件夹README指南。在创建README.md文件时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
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.