github-skill-adoption-audit

name

github-skill-adoption-audit

description

Audit GitHub repositories that publish agent skills and summarize real adoption signals: stars, forks, watchers, issues, recent views, clones, referrers, popular paths, directory/marketplace indexing, and external references. Use when Codex is asked whether a skill repo has users, how many stars it has, whether people are cloning it, which repo is getting traction, or how to prioritize skill promotion.

GitHub Skill Adoption Audit

Overview

Measure whether a public skill repository is being discovered or used. Separate hard signals such as stars and unique cloners from weak signals such as generic search hits.

Read references/adoption-signals.md when interpreting results.

Workflow

1. Resolve the repository set.

   • If the user names a repo, inspect only that repo.
   • If the user says "my skills", discover likely skill repos from local git remotes or gh repo list <owner>.

2. Gather GitHub metadata.

   • Use gh repo view for stars, forks, watchers, issues, PRs, visibility, pushed date, and URL.
   • Use GitHub traffic endpoints for views, clones, referrers, and popular paths when the authenticated user has permission.

3. Check external discovery.

   • Search for exact repo names, install commands, and unique skill phrases.
   • Treat generic skill names as weak evidence unless the result clearly points back to the user's repo.
   • Note GitHub code-search rate limits rather than retrying aggressively.

4. Interpret cautiously.

   • Stars show public endorsement.
   • Unique clones suggest installation or inspection, but may include bots, mirrors, CI, or the owner.
   • Views/referrers show discovery channels for the last GitHub traffic window, usually about 14 days.
   • Marketplace indexing is discoverability, not proof of active use.

5. Output a short decision.

   • Identify the strongest repo.
   • List star count and traffic counts.
   • Say what is not yet proven.
   • Recommend one practical next action: README demo, screenshot, release, example task, marketplace metadata, or targeted distribution.

Script

Run the bundled audit script when gh is authenticated:

python3 scripts/audit_skill_repos.py \
  --owner walterkken \
  --repos doc-driven-engineering-software-skills matlab-simulink-agent-skill \
  --output skill-adoption-audit.md

It writes a markdown report and a sibling JSON file. If traffic endpoints fail, the report should still include public metadata and the exact permission/rate limit issue.