readme_skill

Overview

This skill updates a project's README.md with clear, up-to-date documentation based on the current codebase. It inspects project files and configuration to infer features, tech stack, installation steps, and structure, then generates a polished Markdown README. It preserves existing human-written sections when present.

How this skill works

The skill scans the repository root and reads common config files (package.json, requirements.txt, rust/Cargo files, toml configs) and source directories (app/, src/, components/, lib/). It reads any existing README and optional task notes to preserve manual instructions, then synthesizes a complete README with title, description, features, tech stack, prerequisites, installation, structure, workflows, and license notes. Finally, it validates Markdown formatting and checks for obvious broken links.

When to use it

• The current README is missing or sparse and you need a ready-to-use documentation file.
• The codebase changed significantly and the README is outdated.
• You want a consistent README format across projects for onboarding or publishing.
• You need README content that reflects installed dependencies and detected frameworks.
• Before publishing the project or creating a release to ensure docs are accurate.

Best practices

• Keep the README focused and actionable: quick start first, deeper details later.
• Preserve any manual or sensitive instructions from the existing README; do not overwrite without review.
• Run the skill after major dependency or architecture changes to keep docs aligned with code.
• Manually review generated commands (scripts, ports, env vars) before sharing publicly.
• Add project-specific examples or badges after generation to reflect CI, coverage, or deploy status.

Example use cases

• Generate a complete README for a freshly scaffolded Node.js or Python app with detected packages and start scripts.
• Update docs for a frontend app by listing directories like src/, components/, public/ and dev server commands.
• Refresh README for a microservice with Docker and deploy config (Dockerfile, fly.toml) including prerequisites and run instructions.
• Create a README that highlights available agent workflows or automation skills present in the repo.
• Produce a license and contribution note when a LICENSE file is detected.