Repository AI Discoverability Audit

Audit a repository’s visibility to AI coding agents and developer search.

Mindset: AI agents are becoming the primary way developers discover libraries. A functionally strong library that scores poorly on machine-readable signals will never get recommended. This command measures the gap between code quality and discoverability, and surfaces what polish can fix vs. what requires usage evidence that polish alone cannot create.

Resource Hint: sonnet - structured audit with concrete rubrics, optional content drafting

When to Use

• Before publishing or promoting a library
• Periodic audit of existing public repositories
• After /pb-repo-enhance to measure remaining discoverability gaps
• When a library has low adoption despite solid code
• Fleet-wide audit across an org (--status mode)

Objective

Produce a scorecard measuring how well a repository converts when discovered by AI agents or developer search. Five scored dimensions (0-3 each, max 15) plus an informational usage evidence section that honestly surfaces what polish cannot fix.

Invocations

/pb-repo-polish owner/repo           Full audit: scorecard + action items
/pb-repo-polish owner/repo --draft   Audit + generate content drafts (llms.txt, README sections)
/pb-repo-polish --status             Fleet view: which repos polished, scores

Review Checklist

Dimension 1: Search Term Alignment (0-3)

Does the description, README, and topics contain the words developers actually search?

How to assess: Think about what a developer would type into Google, pkg.go.dev, npm, or ask an AI agent. Compare those terms against the repo’s description, README opening paragraph, and GitHub topics. Misalignment here is the highest-ROI fix for small libraries.

Dimension 2: README Machine-Readability (0-3)

Can an AI agent extract what this library does, how to install it, and when to use it from the README alone?

How to assess: Read the README as if you have zero context. Can you answer: what does it do, how do I install it, show me an example, when should I use this vs. alternatives? Each missing answer costs a point.

Dimension 3: Registry Presence (0-3)

Is the library findable and current on the expected package registry?

How to assess:

• Go: check pkg.go.dev/{module} - is it indexed? Is the latest version shown? Is the module path correct (especially /v2 suffixes)?
• Node: check npmjs.com/package/{name} - is it published? Is the latest version current?
• Other: check the language-appropriate registry

Dimension 4: Metadata Completeness (0-3)

Does GitHub metadata make the repo discoverable and credible at a glance?

How to assess: Run gh repo view owner/repo --json description,repositoryTopics,licenseInfo,homepageUrl and evaluate against the rubric. Topics should include the language, the problem domain, and the specific technique.

Dimension 5: Examples Quality (0-3)

Can a developer copy-paste a working example without reading the full source?

How to assess: Check for examples/ directory. If it exists, verify examples compile/run and have complete import statements. Problem-oriented means each example solves a specific use case, not just “basic usage.”

Dimension 6: Usage Evidence (informational, not scored)

Surface the signals that polish cannot create. This section is honest about what metadata improvements can and cannot do.

What to check:

• Dependents count (pkg.go.dev “Imported by” or npm dependents)
• Download stats (npm weekly downloads)
• External references (blog posts, Stack Overflow mentions, conference talks)
• Stars and forks (weak signal but still signal)

Scoring

Max score: 15 (5 dimensions x 3 points each)

Deliverables

Scorecard (always produced)

## AI Discoverability Scorecard: {owner}/{repo}

| # | Dimension | Score | Notes |
|---|-----------|-------|-------|
| 1 | Search Term Alignment | X/3 | {specific finding} |
| 2 | README Machine-Readability | X/3 | {specific finding} |
| 3 | Registry Presence | X/3 | {specific finding} |
| 4 | Metadata Completeness | X/3 | {specific finding} |
| 5 | Examples Quality | X/3 | {specific finding} |
|   | **Total** | **X/15** | **{tier}** |

## Usage Evidence

Dependents: N (pkg.go.dev) / N (npm)
Downloads: ~N/week (npm only)
External references: {found or "none found"}

Note: Metadata polish improves conversion but not discovery.
For this repo to be recommended by AI agents, it needs usage
evidence: blog posts, SO answers, or dependents that reference it.

Action Items (always produced)

Ordered by impact. Each item is concrete and actionable:

## Action Items (ordered by impact)

1. **[Dim X]** {Specific action} - {why this moves the score}
2. **[Dim X]** {Specific action} - {why this moves the score}
...

Content Drafts (–draft flag only)

When --draft is passed, produce these after the scorecard:

1. llms.txt draft (P2 - experimental format, not widely consumed yet):

# {name}
> {one-line from description}

## What it does
{2-3 sentences}

## Install
{install command}

## Quick start
{minimal working example}

## API
{key functions/types}

## When to use this
{use cases}

## When NOT to use this
{anti-use-cases, alternatives}

2. README “When to use this” section - comparison anchor against the dominant alternative. Format:

## When to Use This

Use {name} when you need {specific scenario}.

**Choose {name} over {alternative} when:**
- {differentiator 1}
- {differentiator 2}

**Choose {alternative} instead when:**
- {scenario where alternative wins}

3. Description improvement - if search terms are missing from the current description, draft a better one (max 160 chars).

4. Metadata fix commands - exact gh repo edit commands:

gh repo edit owner/repo --description "new description"
gh repo edit owner/repo --add-topic topic1 --add-topic topic2

Fleet View (–status mode)

## AI Discoverability Status: {org}

| Repo | Score | Tier | Last Audited | Top Gap |
|------|-------|------|-------------|---------|
| repo-1 | 12/15 | Functional | 2026-03-01 | Examples |
| repo-2 | 8/15 | Gaps | 2026-02-15 | Search terms |
| repo-3 | -- | Not audited | -- | -- |

Process

Step 1: Gather Data

# Repository metadata
gh repo view owner/repo --json description,repositoryTopics,licenseInfo,homepageUrl

# README content
gh api repos/owner/repo/readme --jq '.content' | base64 -d

# Check for examples directory
gh api repos/owner/repo/contents/examples 2>/dev/null

# Registry check (Go)
# Visit pkg.go.dev/{module-path}

# Registry check (Node)
# Visit npmjs.com/package/{name}

Step 2: Score Each Dimension

Walk through each dimension’s rubric. Be precise: score what exists, not what could exist.

Step 3: Identify Search Terms

Think like a developer searching for this type of library:

• What problem are they solving?
• What words would they type?
• Compare against description, README first paragraph, and topics

Step 4: Produce Scorecard + Action Items

Use the deliverable templates above. Action items ordered by score impact (biggest gaps first).

Step 5: Draft Content (–draft only)

Generate llms.txt, “When to use this” section, improved description, and gh repo edit commands.

Anti-Patterns to Avoid

Related Commands

• /pb-repo-enhance - Full repository polish (organize + docs + presentation)
• /pb-repo-about - Generate GitHub About section + tags
• /pb-repo-readme - Write or rewrite project README
• /pb-repo-organize - Clean up project root structure

Discoverable repo, discoverable library.