Write README Skill

You are an expert at writing clear, useful project READMEs. When this skill is invoked, create or update the project’s README.

What This Skill Does

Analyzes the project structure, code, and configuration to produce a comprehensive README that helps new users and contributors get started quickly.

Step-by-Step Instructions

1. Analyze the project. Examine:

   • package.json, Cargo.toml, pyproject.toml, or equivalent for project metadata
   • Directory structure and main entry points
   • Existing README (if updating)
   • Configuration files for tech stack details
   • CI/CD configuration for build and test commands
   • License file
   • Contributing guidelines

2. Determine the audience. Check if this is:

   • A library (audience: developers who will use it)
   • An application (audience: users who will run it)
   • An internal tool (audience: team members)
   • Adjust the tone, depth, and emphasis accordingly

3. Write the README sections:

   Title and Description

   • Project name and a one-paragraph description of what it does and why it exists

   Quick Start / Getting Started

   • Prerequisites (runtime versions, tools needed)
   • Installation steps (exact commands)
   • Running the project locally (exact commands)
   • Verify it works (what you should see)

   Usage

   • Basic usage examples
   • Common use cases
   • Configuration options

   Development

   • How to set up the development environment
   • How to run tests
   • How to run linting
   • How to build

   Project Structure (if helpful)

   • Key directories and what they contain
   • Entry points

   Deployment (if applicable)

   • How to deploy
   • Environment variables needed

   Contributing (if open source)

   • How to submit changes
   • Code style expectations
   • Link to CONTRIBUTING.md if it exists

   License

   • License type and link

4. Verify accuracy. Ensure every command in the README actually works:

   • Test installation commands
   • Test run commands
   • Verify file paths referenced in the README exist

5. Write or update the file. If a README exists, update it preserving any sections the user has customized. If no README exists, create one.

Guidelines

• Put the most important information first. Quick Start before deep dives.
• Every command should be copy-pasteable. Use code blocks with the correct language tag.
• Do not assume knowledge. Spell out prerequisites explicitly.
• Keep it current. Remove references to deprecated features.
• Use consistent formatting: headings, bullet points, code blocks.
• Do not use badges unless the project already has them or the user requests them.
• If the project has a docs site, link to it rather than duplicating content.
• Keep the README focused. Long sections should link to separate docs.
• Test every command you write. A README with broken commands is worse than no README.