GitHub README and Profile Writing

Serve the primary reader first, then discovery, trust, contribution, and appropriate conversion.

Before writing

Inspect the repository first. Ask only what changes the README: audience, status, intended action, canonical URLs, approved claims, screenshots or demos, license, support channel, services, and type (project, organization, skill, profile). Keep the user's wording. Never invent metrics, testimonials, users, revenue, partners, or capabilities, and never publish secrets, private client details, or unapproved logos. For personal profiles, read profile-readme.md.

Structure

Default order: what it is and who it helps → why it matters → fastest install or try → minimal working example → proof (demo, screenshot, architecture, status) → deeper docs and contribution → one next action (use, star, feedback, contribute, contact, hire). Include only sections with real content; a short complete README beats a long placeholder.

• Project: problem → value → install → quick start → features → demo → architecture → roadmap → contributing → license.
• Skill: purpose → install command → starter prompt → workflow → optional companions → limitations → related skills → feedback.
• Organization: mission → products or services → proof → open source → contact.

Proof and badges

Put one strong, current, public proof near the top when the project is visual: screenshot, short GIF/video, or live demo for UI; rendered example or playground for libraries; terminal session for CLIs; request/response or architecture diagram for APIs. Meaning stays in text with descriptive alt text; no decorative image walls.

Badges are optional proof: three to six at most, accurate and linked—release, CI, meaningful coverage, license, docs or demo, authoritative package/download counts. No fake stars, visitor counters, animated walls, or per-dependency badges.

Discoverability

Plain category phrase in the title, first sentence, and one heading; descriptive headings, links, alt text, topics, canonical URLs; natural synonyms; link the specific project first, then the repo root; no keyword stuffing, hidden text, or boilerplate. Keep the repo description, topics, website, social preview, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, license, templates, and changelog aligned—link deeper docs instead of duplicating them, and never link empty placeholders.

Before publishing

Verify URLs; test install and quick start on a clean environment when possible; label current, beta, planned, and deprecated features; check links, alt text, code fences, narrow-width and dark-mode rendering. Services and affiliate links appear only when relevant and clearly labeled.

Output

Propose structure and content before overwriting an existing README unless direct replacement is authorized. Include a link checklist, missing evidence, and suggested follow-up assets.