topics

Validates and applies GitHub repository topics via a deterministic selection engine.

Updated Apr 25, 2026
One-click install
npx skills add https://github.com/ozzy-labs/skills --skill topics-ozzy-labs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: topics
Source: https://github.com/ozzy-labs/skills/tree/main/.claude/skills/topics
Command: npx skills add https://github.com/ozzy-labs/skills --skill topics-ozzy-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Choosing GitHub repository topics by hand leads to constraint violations, redundant broad/narrow or singular/plural duplicates, and inconsistent naming conventions, all of which hurt repository discoverability. ## Core Features & Use Cases - Deterministic topic vetting: The bundled topics.mjs engine validates GitHub's official constraints (lowercase, hyphens, 50-char limit, max 20 topics), measures popularity via gh api search/repositories, and applies broad+narrow 5x thresholding and singular/plural comparison. - Hardcoded ozzy-labs conventions: Canonicalizes multi-agent, strips -cli suffixes (codex-cli, gemini-cli, copilot-cli), and retains claude + claude-code together. - Policy-gated application: Default plan mode returns an apply command for batch confirmation; --apply executes gh repo edit --add-topic and verifies with gh repo view; --dry-run analyzes only. - Use Case: Given candidates like ai,ai-agents,codex-cli,multi-agents, the engine normalizes them, compares popularity, and produces a final vetted topic list ready to apply to the repository. ## Quick Start Ask the assistant to run the topics skill with a comma-separated candidate list such as "ai, agents, claude-code" in dry-run mode to see the vetted topic selection before applying it to the repository.

Frequently Asked Questions about topics

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose GitHub repository topics automatically?▼

Pass a comma-separated candidate list to the topics.mjs engine, which validates GitHub's official constraints, measures each topic's popularity via gh api search/repositories, and returns a vetted final list. Run with --apply to execute gh repo edit --add-topic after confirmation.

How to compare broad and narrow GitHub topics for a repo?▼

The engine detects broad/narrow pairs (e.g. ai vs ai-agents) and drops the narrow term when the broad term has at least 5x the repository count. If the narrow term is more popular, the decision defers to hardcoded conventions instead of automatic pruning.

Does the topics skill work outside ozzy-labs repositories?▼

No, its scope is limited to ozzy-labs use. It hardcodes organization-specific conventions such as multi-agent canonicalization, -cli suffix stripping for codex-cli/gemini-cli/copilot-cli, and retaining claude alongside claude-code.

What happens when GitHub topic popularity lookup fails?▼

A failed gh query yields a null count with a classified error reason such as rate limit, network, or gh not authenticated. That topic is excluded from the 5x and singular/plural comparisons rather than being treated as zero popularity.

Why did the topics engine reject some of my candidates?▼

Candidates are rejected when they violate GitHub's official constraints: uppercase or invalid characters, length over 50, or leading/trailing hyphens. The engine reports each rejected topic with its reason and never calls the API when all candidates fail validation.