readme-writing_skill

Overview

This skill automates writing and optimizing a project's README.md following standard conventions and a strict template. It ensures documentation accuracy by extracting real project data and prevents introducing fictional files or settings. The skill is triggered during README creation, review, or refactor tasks to maintain consistent, high-quality docs.

How this skill works

The skill inspects repository artifacts in priority order: dependency manifests (pyproject.toml, package.json, Cargo.toml, go.mod), lock files, infrastructure definitions (Dockerfile, docker-compose.yml, k8s/), environment examples (.env.example, config/), entrypoints (main.py, index.ts, main.go) and project tree. It fills template sections with only verifiable items, generates architecture diagrams when multi-service or external dependencies exist, and omits optional sections unless corresponding files or conditions are found. It validates placeholders against actual files to avoid fictional content.

When to use it

• Creating a new README for a repository
• Updating README after dependency, config, or entrypoint changes
• Refactoring docs to meet organization or open-source standards
• Preparing documentation for release or handoff to other teams
• Automating README generation in CI when manifest files change

Best practices

• Always source values from repository files rather than guessing
• Include only sections that correspond to detected files or settings
• Keep prose concise and fact-based; avoid marketing language
• Use tested commands in Quick Start and verify environment variable names exactly
• Add Architecture only when service boundaries or external dependencies exist
• Validate generated README against the file tree and manifest contents before committing

Example use cases

• Generate README for a Python project using pyproject.toml and main.py
• Update Tech Stack and Quick Start after dependency version changes
• Create Directory Structure and Configuration sections from detected config/ and .env.example
• Produce an Architecture mermaid diagram when docker-compose.yml or k8s manifests are present
• Convert existing loose notes into a standards-compliant README for open-source release