Agent Skills

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.

This site is open source. View this page on GitHub.