Optimize GitHub profiles and READMEs for developer discovery

This skill optimizes a project's GitHub presence, since GitHub is often where developers do their first technical evaluation of a project. It defines the anatomy of a great README with a required/recommended section table (logo/banner, badges, a one-sentence description, a hero example, features, a quick start under two minutes, installation, usage, documentation links, contributing, and license), and provides a full README template with badge placement, a feature list, and quick-start code. It categorizes badges into trust-signal badges (CI/build status, version, license, downloads, coverage, security) and community badges (Discord members, GitHub stars, contributors, last commit), names the services that generate them (Shields.io, Badgen, native GitHub badges), and gives copy-pasteable badge markdown for each. For profile READMEs it covers the username/username repository trick that surfaces a README on the GitHub profile page itself, a template structure (intro, current work, a projects table, an automated recent-posts block, connect links, and a GitHub-stats image), and a do/don't table (scannable over paragraphs, best projects over an exhaustive list, current work over stale content). On discoverability it covers GitHub Topics strategy (technology, framework, use-case, category, and problem-based topics, up to 20 per repo) and what GitHub search actually weighs - repository name, a 350-character keyword-rich description, full-text-indexed README content, topics, and auto-detected language - plus a five-step process for getting listed on relevant awesome-lists (find them, check their quality/activity/docs requirements, meet the criteria, submit a PR, then wait out the curation process), naming several popular ones (awesome-cli-apps, awesome-selfhosted, awesome-nodejs, awesome-python, awesome-go, awesome-rust, awesome-devops). It also covers GitHub Actions for marketing automation - a scheduled workflow to update a blog-post list in the README, a metrics-image action, and a release-announcement action that posts a tweet on publish - plus setting up GitHub Sponsors with a funding.yml example and a four-tier sponsor pricing table (Supporter/Backer/Sponsor/Enterprise). It closes with a platform do's-and-don'ts list, a table of GitHub metrics worth tracking (stars, forks, clones, traffic, referrers, contributors) accessible via the repo's Insights → Traffic page, and a twelve-item README audit checklist.

Use it when optimizing a GitHub profile, README, or project discoverability - writing or auditing a README, setting up a profile README, choosing topics, or preparing an awesome-list submission. It recommends first reading a companion developer-audience-context file if one exists, and auditing the current profile, pinned repos, and READMEs before making changes. Do NOT use its badge guidance to cram in every available badge - the skill's own don't-list flags too many badges as visual clutter - and don't submit to an awesome list before actually meeting its stated quality/activity/documentation requirements, since that wastes the submission and the curator's time.

Inputs: the project's current README, profile, pinned repos, and topics. Outputs: a restructured README following the required-section template, badge markdown for CI/version/license/community signals, a profile README with a projects table and stats image, a chosen set of up-to-20 GitHub Topics, an awesome-list submission plan, GitHub Actions workflows for automated README updates and release announcements, a funding.yml for GitHub Sponsors with tiered pricing, and a completed README audit checklist.

npm install project-name

Names Shields.io and Badgen for badge generation, GitHub Readme Stats and the lowlighter/metrics action for profile stats images, gautamkrishnar/blog-post-workflow for automated blog-post lists, ethomson/send-tweet-action for release-announcement tweets, Carbon for code screenshots, readme.so as a README generator, GitHub Sponsors with funding.yml (supporting Patreon, Open Collective, Ko-fi, and custom links), and Octolens for monitoring GitHub mentions of the project or competitors. It also references companion skills - developer-audience-context, hacker-news-strategy, reddit-engagement, and dev-to-hashnode.

Open-source maintainers and developer-marketing teams who want their GitHub README, profile, and topics to convert a first-time visitor's technical evaluation into a star, contribution, or install.