# Repomatic Topics

> Optimize a repository's GitHub topics. Analyze the competition on each topic page, then pick the topics that make the project easier to find.

- Skill: `kdeldycke/repomatic-topics` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kdeldycke/repomatic-topics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kdeldycke/repomatic-topics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kdeldycke (https://skillmd.com/u/kdeldycke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kdeldycke/repomatic-topics

---


## Context

!`grep -A1 '^\[project\]' pyproject.toml 2>/dev/null | tail -1`
!`gh api repos/{owner}/{repo} --jq '.topics | join(", ")' 2>/dev/null || echo "NO_GH_ACCESS"`

## Instructions

You help users optimize their GitHub repository topics (tags) for maximum discoverability, balancing accuracy with competitive positioning on GitHub topic pages.

### Determine repository

- Read `pyproject.toml` for the project name, description, and `keywords` list.
- Use `gh api` to fetch the current GitHub topics from the repo.

### Argument handling

- `audit` (default when `$ARGUMENTS` is empty): Analyze current topics and recommend changes. Do not apply.
- `apply`: Analyze, confirm with the user, then apply via `gh api --method PUT repos/{owner}/{repo}/topics`.

### Analysis process

1. **Inventory features.** Read the codebase (CLI commands, workflows, config options) to understand what the project actually does.

2. **Assess current topics.** For each existing topic, fetch `https://github.com/topics/{topic}` and evaluate:

   - How many repos use the topic.
   - What star count is needed to appear on page 1 (above the fold).
   - Whether this repo can realistically rank there.

3. **Classify competitiveness.** For each topic:

   - **High competition** (page 1 requires 10k+ stars): effectively invisible. Drop unless the topic is core identity.
   - **Medium** (page 1 requires 1k-10k stars): keep only if the repo is borderline viable.
   - **Low/niche** (page 1 requires \<1k stars or few total repos): high ROI — keep or add.

4. **Propose candidate topics.** Search for niche topics where the repo could rank in the top 3. Look for:

   - Feature-specific topics (e.g., `github-labels`, `reusable-workflows`) over generic ones (e.g., `labels`, `ci-cd`).
   - Compound topics that narrow the audience (e.g., `python-automation` vs `automation`).
   - Topics with few repos where claiming them gives instant #1 ranking.

5. **Present recommendations.** Show a table with:

   - Topics to keep (with rank assessment).
   - Topics to drop (with reason: too competitive, inaccurate, etc.).
   - Topics to add (with repo count and expected rank).

GitHub allows up to 20 topics. Fill all 20 slots — unused slots are wasted discoverability.

### Required topics for awesome lists

If the repository name starts with `awesome-`, it must have both the `awesome` and `awesome-list` topics. This is enforced by [awesome-lint](https://github.com/sindresorhus/awesome-lint/blob/main/rules/github.js). Flag any missing required topic during audit, and add them during apply.

### After analysis

- Confirm changes with the user before applying.
- When applying, update both GitHub topics (`gh api --method PUT repos/{owner}/{repo}/topics`) and `pyproject.toml` keywords to stay in sync.
- The `pyproject.toml` keywords serve PyPI search — keep them aligned with GitHub topics.

### Next steps

Push the change: `lint.yaml` validates the updated `pyproject.toml`, and the new GitHub topics take effect immediately.