Optimize GitHub profiles and READMEs for developer discovery

GitHub Presence

When to Use

Use this skill when you need when the user wants to optimize their GitHub profile, README, or project discoverability. Trigger phrases include "GitHub README," "README optimization," "GitHub profile," "GitHub stars," "GitHub discoverability," "awesome lists," or "GitHub marketing.".

GitHub is where developers evaluate your project before trying it. This skill covers README optimization, profile READMEs, discoverability through topics and awesome lists, and using GitHub features for marketing.

Before You Start

1. Read .agents/developer-audience-context.md if it exists
2. Audit your current GitHub presence (profile, pinned repos, READMEs)
3. Understand: GitHub is often the first technical evaluation - optimize accordingly

README Structure

The Anatomy of a Great README

README Template

<div align="center">
  <img src="logo.svg" alt="Project Name" width="200">
  <h1>Project Name</h1>
  <p><strong>One compelling sentence explaining what this does.</strong></p>

  
  <a href="https://github.com/org/repo/actions"><img src="https://github.com/org/repo/workflows/CI/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/name"><img src="https://img.shields.io/npm/v/name.svg" alt="npm version"></a>
  <a href="https://github.com/org/repo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  <a href="https://discord.gg/invite"><img src="https://img.shields.io/discord/123456789" alt="Discord"></a>

  <br>
  <br>

  <a href="https://docs.example.com">Documentation</a> •
  <a href="https://example.com">Website</a> •
  <a href="https://discord.gg/invite">Discord</a>
</div>

---

### Why Project Name?

- **Feature 1** — Brief explanation
- **Feature 2** — Brief explanation
- **Feature 3** — Brief explanation

### Quick Start

```bash
npm install project-name

import { thing } from 'project-name';

const result = thing.doSomething();
console.log(result);

Installation

npm

npm install project-name

yarn

yarn add project-name

pnpm

pnpm add project-name

Usage

Basic Example

// Code example with comments

Advanced Example

// More complex example

Documentation

Full documentation available at docs.example.com

• Getting Started
• API Reference
• Examples

Badges That Matter

Trust Signal Badges

Community Badges

Badge Services

Badge Examples

![CI](https://github.com/org/repo/workflows/CI/badge.svg)


[![npm](https://img.shields.io/npm/v/package-name.svg)](https://www.npmjs.com/package/package-name)


[![Downloads](https://img.shields.io/npm/dm/package-name.svg)](https://www.npmjs.com/package/package-name)


[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)


[![Discord](https://img.shields.io/discord/SERVER_ID?color=7289da&logo=discord&logoColor=white)](https://discord.gg/invite)


[![GitHub stars](https://img.shields.io/github/stars/org/repo?style=social)](https://github.com/org/repo)

Profile README

Setting Up Profile README

1. Create a repository with your username (e.g., github.com/yourname/yourname)
2. Add a README.md file
3. This displays on your profile page

Profile README Structure

#### Hi, I'm [Name] 👋

[One sentence about what you do]

#### What I'm Working On

- 🔭 Building [project] - [brief description]
- 🌱 Learning [technology]
- 💬 Ask me about [expertise areas]

#### Projects

| Project | Description | Stars |
|---------|-------------|-------|
| [Project 1](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/github-presence/link) | Brief description | ![Stars](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/github-presence/badge) |
| [Project 2](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/github-presence/link) | Brief description | ![Stars](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/github-presence/badge) |

#### Recent Blog Posts





#### Connect

[![Twitter](https://img.shields.io/badge/-Twitter-1DA1F2?style=flat&logo=twitter&logoColor=white)](https://twitter.com/handle)
[![LinkedIn](https://img.shields.io/badge/-LinkedIn-0077B5?style=flat&logo=linkedin&logoColor=white)](https://linkedin.com/in/handle)

#### GitHub Stats

![Your GitHub stats](https://github-readme-stats.vercel.app/api?username=yourusername&show_icons=true)

Profile README Best Practices

Discoverability

GitHub Topics

Topics are how people find repositories. Optimize for search.

Add topics: Repository settings → Topics (up to 20)

Search Optimization

GitHub search considers:

1. Repository name — Include main keyword
2. Description — 350 chars, keyword-rich
3. README content — Full text indexed
4. Topics — Category matching
5. Language — Auto-detected

Awesome Lists

Getting on awesome lists drives traffic and credibility.

Popular awesome lists for dev tools:

• awesome-cli-apps
• awesome-selfhosted
• awesome-nodejs
• awesome-python
• awesome-go
• awesome-rust
• awesome-devops

GitHub Actions for Marketing

Automated README Updates

#### .github/workflows/readme-update.yml
name: Update README

on:
  schedule:
    - cron: '0 0 * * *'  # Daily
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Example: Update blog post list
      - uses: gautamkrishnar/blog-post-workflow@master
        with:
          feed_list: "https://yourblog.com/feed"

      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add -A
          git diff --quiet && git diff --staged --quiet || git commit -m "Update README"
          git push

Metrics and Stats

#### Auto-update GitHub stats image
- uses: lowlighter/metrics@latest
  with:
    token: ${{ secrets.METRICS_TOKEN }}
    filename: github-metrics.svg

Release Announcements

#### Tweet on new release
name: Release Announcement
on:
  release:
    types: [published]

jobs:
  announce:
    runs-on: ubuntu-latest
    steps:
      - name: Tweet
        uses: ethomson/send-tweet-action@v1
        with:
          status: "🚀 ${{ github.repository }} ${{ github.event.release.tag_name }} released! ${{ github.event.release.html_url }}"
          consumer-key: ${{ secrets.TWITTER_CONSUMER_KEY }}
          # ... other secrets

GitHub Sponsors

Setting Up Sponsors

1. Join GitHub Sponsors (github.com/sponsors)
2. Create compelling tier descriptions
3. Set up funding.yml in repos

funding.yml example:

github: [yourusername]
patreon: yourpatreon
open_collective: yourproject
ko_fi: yourkofi
custom: ["https://buymeacoffee.com/you"]

Sponsor Tiers That Work

Platform-Specific Do's and Don'ts

Do's

1. Do optimize your README for first impression
2. Do use badges for quick trust signals
3. Do add relevant topics (up to 20)
4. Do keep your profile README current
5. Do respond to issues and PRs promptly
6. Do pin your best repositories
7. Do include clear installation instructions
8. Do submit to relevant awesome lists

Don'ts

1. Don't neglect the README - it's your landing page
2. Don't use too many badges (cluttered)
3. Don't let issues pile up unanswered
4. Don't forget a license file
5. Don't use low-quality or broken images
6. Don't write walls of text without structure
7. Don't ignore contribution guidelines

Measuring Success

GitHub Metrics to Track

Traffic Insights

Access via: Repository → Insights → Traffic

• Views and unique visitors
• Popular content (which files)
• Referring sites
• Clone activity

Tools

README Audit Checklist

• Clear, keyword-rich name and description
• Badges show CI status, version, license
• One-liner explains what it does
• Quick start gets users running in < 2 min
• Code examples are copy-pasteable
• All links work and are HTTPS
• Images have alt text
• Mobile-readable formatting
• License file present
• Contributing guidelines exist
• Topics are set (up to 20)
• Social preview image uploaded

Related Skills

• developer-audience-context - Know who evaluates your repo
• hacker-news-strategy - HN users check GitHub before upvoting
• reddit-engagement - Redditors evaluate via GitHub
• dev-to-hashnode - Link from README to content

Limitations

• Use this skill only when the task clearly matches its upstream source and local project context.
• Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
• Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.