agentleFS
bestdeejay-designbestdeejay-design/agent-skills/skills/repo-metadata-health/SKILL.md

repo-metadata-health

Skill6 starsChanged 3 months agoMITView on GitHub

Audit and update GitHub repository metadata and community health: description (gh repo edit), topics (PUT /repos/topics, max 20), GitHub Pages link + homepage, community-health percentage via the Community Profile API, and a 16-point check checklist. Script: validate_repo.py (gh API + filesystem, auto-detect from git remote). Triggers: 'repo description', 'repo topics', 'github topics', 'github pages', 'community health', 'repo audit', 'repo metadata', 'repo checklist', 'health percentage', 'repo about'.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to audit and update a repository's metadata and community health: description, topics, GitHub Pages link, homepage in About, …

    line 14
  2. Distinctive:

    all significant components: must be reflected in both description and topics

    line 57
  3. Very specific:

    If Pages is enabled (gh api repos/<owner>/<repo>/pages):

    line 61
  4. Very specific:

    Do not use to author legal/community files.

    line 92

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Repo Metadata Health — description, topics, Pages, community health

Use this skill to audit and update a repository's metadata and community health: description, topics, GitHub Pages link, homepage in About, and the Community Standards percentage. Keeps the GitHub page accurate after major changes.

When to use

  • A repository's description/topics are outdated after a major change.
  • Need the Community Health score (Community Profile API) audited against a 16-point checklist.
  • GitHub Pages should be linked in README/About.
  • User asks for "repo description", "repo topics", "github pages", "community health", "repo audit", "repo checklist".

Do NOT use

  • For README content/visual header/footer — use repo-readme-assets.
  • For legal/community files (LICENSE, CONTRIBUTING, SECURITY, templates) — use repo-community-files.
  • For the social preview PNG — use repo-social-preview.

Files

  • SKILL.md — this file
  • scripts/validate_repo.py — 16-point checklist (gh API + filesystem, auto-detect from git remote)
  • references/community-checklist.md — the full 16-point checklist with check commands
  • examples/repo-hygiene.yml — CI example wiring the checklist into a workflow

Description and topics

Set via gh api:

# Description (UI limit ~350 chars) — list ALL key components
gh repo edit --description "<full description with keywords>"

# Topics (array via -f 'names[]=...') — PUT only, full list replacement
gh api -X PUT repos/<owner>/<repo>/topics \
  -f 'names[]=python' -f 'names[]=markdown' -f 'names[]=documentation' \
  -f 'names[]=agents' -f 'names[]=skills' -f 'names[]=opencode'

Topic rules:

  • max 20 topics per repository (GitHub limit)
  • each topic: ≤ 50 chars, lowercase letters/digits/hyphens only
  • include language/framework/DB/broker (key ones), architectural patterns, project type
  • all significant components must be reflected in both description and topics

GitHub Pages

If Pages is enabled (gh api repos/<owner>/<repo>/pages):

  • README must contain a working link https://<owner>.github.io/<repo>/
  • About "Website" field = Pages URL (gh repo edit --homepage https://…)

Community health audit

The 16-point checklist (files → metadata → community health → releases → final) with check commands: references/community-checklist.md.

Automated run:

python3 scripts/validate_repo.py            # auto-detect from git remote
python3 scripts/validate_repo.py owner/repo # explicit repository

The canonical baseline is the GitHub Community Profile API (GET /repos/{owner}/{repo}/community/profile, metric health_percentage; reference repo github/docs = 100%). See references/community-checklist.md for the full file checklist and the canonical analogues (org-level default health files, gh CLI, GitHub REST API endpoints).

Anti-patterns

  • Topics replaced via POST (only PUT replaces the full list).
  • Description that does not cover all significant components.
  • Pages enabled but not linked in README/About.
  • Broken or stale community-health files lowering the percentage.

Boundaries

  • Do not use to author legal/community files; use repo-community-files.

Evidence and completion gate

Run the documented command against the user’s actual input. Report the command, exit status, files changed or produced, and relevant stdout/stderr. Separate blocked or pre-existing failures from failures introduced by the current work. Do not call the result complete when the script was only described or when an artifact was not reopened and checked.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.