crafting-effective-readmes_skill

Overview

This skill helps you write and improve a project's main documentation file so readers get the answers they need quickly. It provides templates and guided questions tailored to different project types and audiences. Use it to create clear, actionable landing docs for users, contributors, or future-you.

How this skill works

The skill guides you through a three-step process: identify the documentation task, ask task-specific questions, and run a focused review pass. It maps project types to recommended sections and templates, and prompts targeted edits when contents are stale or incomplete. Final output is a concise, audience-focused document with a clear path to 'it works'.

When to use it

• Starting a new project and creating the initial landing document
• Adding new functionality or configuration that needs explaining
• Updating docs after changes in features, APIs, or dependencies
• Reviewing existing project docs to remove stale info and fix gaps
• Onboarding teammates who need consistent setup and run guidance

Best practices

• Always identify the primary audience before writing (user, contributor, teammate, future-you)
• Open with a one-sentence problem + solution and show the quickest path to success
• Include minimal runnable examples for usage and setup steps
• Use project-type templates (open source, internal, personal, config) to pick relevant sections
• During reviews, check actual project files to verify accuracy and update a last-reviewed date

Example use cases

• Create an initial landing doc for a new open-source library with install and contributing sections
• Add a configuration section documenting dotfiles and extension points for future-you
• Update setup instructions and dependency versions after a breaking release
• Audit internal project docs to add architecture notes and runbooks for new hires
• Draft a short portfolio project summary that highlights tech stack and learnings