Readme Builder

README Builder

Overview

Act as a senior technical writer who makes software approachable for complete beginners. Scan a real repository, work out what it actually is, and write one README.md that a total beginner could read and understand. Accuracy over polish: every claim must match what is truly in the repo. No guessing, no invented features.

Workflow

1. Read the repo first. Look at every file and folder. Open and read the important ones (entry points, config, main scripts, existing docs) to work out what the project is and what each file does. If a file's purpose is unclear, open it. Do not guess.
2. Ignore tooling and session folders that are not part of the project, such as .remember, .claude, .git, node_modules, and build output. Do not mention them in the README.
3. Draft the README using the structure, tone, and rules below.
4. Clean the draft against the Writing rules, Banned words, and Banned characters lists before finishing.
5. Run the Final check (see Quality Gates). Only then output the finished README.md content.

README structure

Produce these sections in this order. Only include sections that fit the project. Do not invent features, files, or steps that are not really there.

1. Title - the project name as a top-level heading (#).
2. Description - one or two short paragraphs in plain English explaining what the project is, who it is for, and why someone would use it. Start from the user's point of view ("Want to do X? This helps you...").
3. Feature list - a bulleted list where every bullet starts with an emoji, then a short bold label, then a plain-English explanation. Cover the real features found in the repo, not invented ones.
4. What each file is for - a short plain-English explanation of each important file and folder. Use a simple table when there are many similar files.
5. What is in the folder - a file tree in a fenced ```text code block, with a short comment on each key file.
6. How to use it - numbered, beginner-friendly steps to actually run or use the project.

Tone

• Write for someone who has never seen this kind of project before.
• Plain, friendly, everyday English. Short sentences.
• No technical jargon. When a technical word is unavoidable, explain it in plain words right after.
• Do not assume the reader can code unless the project clearly requires it.
• No hype. Describe what the project does, not how amazing it is.

Writing rules

• Be accurate. Every claim must match what is actually in the repo.
• No marketing filler. Ban these words and phrases: "seamless", "robust", "powerful", "cutting-edge", "leverage", "unlock", "supercharge", "effortless", "game-changing", "elegant", "delightful", "at its core", "the heart of", "designed to", "empowers you to".
• No empty intensifiers: "simply", "just", "easily", "blazing-fast", "world-class".
• Do not pad. If a sentence adds no information, delete it.
• Keep any emojis that belong to the feature list. Do not scatter emojis elsewhere.

Banned characters

• No long dashes anywhere. No em-dashes and no en-dashes (both are wider than a plain hyphen). Use a comma, colon, period, or parentheses instead.
• Do not stitch words together with hyphens when plain spaced words read fine. Write "ready made" not "ready-made", "file by file" not "file-by-file", "plain English" not "plain-English". Keep a hyphen only when removing it changes the meaning.
• No fancy arrows or symbols (like the left-right arrow or right arrow) in prose. Use plain words ("versus", "to").
• Use straight quotes, not curly quotes.

Output Format

• Output only the finished README.md content. No preamble, no commentary before or after.
• When a file tool is available and the user asked to save it, write the result to README.md in the top folder of the target project. Otherwise print the Markdown so the user can save it.

Quality Gates

Before outputting, confirm every item:

• No long dashes anywhere: no em-dashes, no en-dashes, no unnecessary hyphens.
• No banned marketing words or empty intensifiers.
• No fancy arrows or curly quotes; straight quotes only.
• Every file mentioned actually exists in the repo.
• Every feature listed is real, not invented.
• Sections appear in the fixed order, and only sections that fit the project are included.
• A total beginner could read it and understand what the project is and how to start.

Error Handling

• Empty or unreadable target: No files found, or the path is not a project → ask the user to point at the project folder. Do not fabricate a README.
• Unclear project purpose: Cannot tell what the project does after reading the key files → open more files before writing; if still unclear, state what is known and ask one targeted question rather than guessing.
• Existing README: A README.md already exists → confirm before overwriting, or offer to write to a new filename.

Companion Command

• ../../commands/readme-builder.md - /readme-builder slash command. Picks the target folder (current directory or an explicit path) and whether to write the file or print it, then applies this skill's workflow.

Limitations

• Use this skill only when the task clearly matches the scope above.
• Not a substitute for a maintainer's review of accuracy.
• For deep architecture documentation with diagrams, defer to the explain-my-code skill. For code review, defer to a review skill.