readme_skill

Overview

This skill generates an absurdly thorough README for a project, covering local setup, architecture, testing, and deployment. It is optimized to get a new developer up and running in minutes and to document production requirements and operational runbooks. Use it to create or update README.md files with complete, practical instructions.

How this skill works

I inspect the repository structure, language manifests (package.json, requirements.txt, pyproject.toml, etc.), configuration and deployment files (Dockerfile, docker-compose, vercel.json, k8s manifests), and common scripts. Based on what I find, I produce a README with sections for prerequisites, step-by-step local setup, architecture diagrams and data flow, environment variables, available scripts, testing, and deployment guidance. I only ask questions when critical details are missing, otherwise I infer sensible defaults and provide recommended commands and snippets.

When to use it

• Initializing documentation for a new or existing project
• Updating README when project structure, deps, or deployment change
• Onboarding new engineers who need a single source of truth
• Preparing a repo for open-source release or internal handoff
• When asked: 'write readme', 'create readme', or 'document this project'

Best practices

• Explore the codebase first: identify entry points, framework, and configs before writing
• Prefer explicit commands and examples that work on a fresh machine
• Detect deployment targets and tailor instructions (Docker recommended if unspecified)
• Include environment variable tables and instructions for secrets management
• Provide runnable scripts and verification steps (health checks, smoke tests)

Example use cases

• Generate a README for a Python backend with Docker and PostgreSQL
• Add a Getting Started guide with step-by-step local setup and database seeds
• Document architecture: request lifecycle, data flow, and key components
• Create a deployment section for Vercel, Fly.io, Kubernetes, or general Docker
• Produce a testing section with commands for unit, integration, and coverage runs