# Repo Description Polish > Audit and polish the GitHub repo description — the pitch shown in search results, previews, and embeds. Proposes a stronger one from README + signals; applies via gh repo edit after approval. Sub-skill of repo-seo-curator. - Skill: `jamestexas/repo-description-polish` (Agent Skill) - Install (CLI): `npx skillmds@latest add jamestexas/repo-description-polish` - Raw SKILL.md: https://api.skillmd.com/api/skills/jamestexas/repo-description-polish/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: jamestexas (https://skillmd.com/u/jamestexas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jamestexas/repo-description-polish --- # /repo-description-polish — GitHub Repo Description Audit the GitHub repository `description` field and propose a polished replacement. ## Arguments `$ARGUMENTS` - **``** — one or more target repos. Defaults to the repo containing the current working directory. - **`--dry-run`** *(default)* — propose only. - **`--apply`** — present proposal, prompt for approval, then write via `gh repo edit`. ## What this solves The description is the *single sentence* that decides whether a stranger clicks. It shows in: - GitHub search results - GitHub repo cards and "related repos" - Hacker News, Slack, Discord link previews (OpenGraph) - Package registries when the repo is linked from a package - LLM-driven "what tools exist for X" recall Bad descriptions are very common in the user's repos: ``` PRIVATE moat 🏰 M.O.A.T: Mixture of Adaptive Tokenizers PRIVATE bread 🥖 PRIVATE smoge 🐉🤖 PRIVATE sushi 🍣 PUBLIC gh-weekly PUBLIC papers PUBLIC x-ray ``` Emoji-only and empty descriptions kill discoverability for both humans and LLMs. ## What a good description looks like ``` ✅ "Workerd-based hypervisor with a declarative Cap'n Proto manifest. Substrate-level identity, audit, and per-bundle credential scoping. Today's primary application: hosting MCP servers behind one HTTP face." (cloister) ✅ "Open-source data plane primitives: arena storage, schema contracts, filesystem projection, tree-sitter AST, LSP integration." (ley-line-open) ``` Pattern: 1. **Category noun first** — what *kind* of thing is this? (`hypervisor`, `library`, `protocol`, `CLI`) 2. **Defining trait** — what distinguishes it from peers in that category? 3. *(Optional)* **Primary use case** — what does someone actually do with it? Length target: 120–250 chars. GitHub truncates around 350 in some surfaces. ## Hard rules - **No emoji-only descriptions.** They convey nothing in search results. - **No starting emoji decoration** unless the project has a strong logo association already. If unsure, drop it. - **No promotional adjectives**: `blazing fast`, `next-gen`, `revolutionary`, `cutting-edge`. Search engines deprioritize, humans skip, LLMs ignore. - **No initialisms without expansion** in the first sentence. "BREAD" alone is opaque; "BREAD (Bidirectional Recurrent Encoder for Anchored Diffusion)" is searchable. - **Lead with the category noun, not the project name.** GitHub already shows the name; you don't need to repeat it. ## Workflow ### Phase 1: Inventory ```bash gh repo view --json name,description,repositoryTopics,visibility,isFork,isArchived,homepageUrl,primaryLanguage ``` Skip with a printed reason if `isFork` or `isArchived`. Continue on private repos only if explicitly named (private repo descriptions still affect search inside an org). ### Phase 2: Signal gathering Read in this priority order: 1. **README first 1000 chars** — the value prop is almost always there if it exists anywhere 2. **`

` or first heading + first paragraph** — often a usable seed 3. **Tagline near top of CLAUDE.md / ARCHITECTURE.md** if present 4. **Package manifest `description` fields** — `package.json`, `Cargo.toml`, `pyproject.toml` 5. **The repo name itself** — what does the name suggest the project is? ### Phase 3: Diagnose the current description Classify the existing description into one of: | Class | Example | Action | | ----- | ------- | ------ | | `empty` | `` | Generate from scratch | | `emoji-only` | `🥖` | Replace | | `vague` | `Some experiments` | Replace with category noun + trait | | `marketing` | `Blazing-fast revolutionary...` | Rewrite, strip adjectives | | `acronym-only` | `BREAD` | Expand and contextualize | | `working` | `Workerd-based hypervisor...` | Leave alone | | `working but stale` | references removed features | Update narrowly | For class `working`, **skip the repo and report**. Don't rewrite working content. ### Phase 4: Proposal Produce one proposal per repo: ``` ## Current: Class: Proposed: Length: chars Rationale: - - - Rejected alternatives: - "" — too vague / too marketing / etc. ``` ### Phase 5: Approval Print all proposals as one document. Then: - `--dry-run` (default): stop. Print a hint to re-run with `--apply`. - `--apply`: print "Apply these N description changes? (yes/no)" and wait. Only proceed on explicit affirmative. ### Phase 6: Apply ```bash gh repo edit "/" --description "" ``` Notes: - Escape inner double quotes if any (rare — descriptions shouldn't have them). - Verify by re-reading with `gh repo view --json description`. ### Phase 7: Report ``` Applied: agentic-research/mache — was: "🗂️ The Universal..." now: "Graph-native code intelligence..." jamestexas/bread — was: "🥖" now: "BREAD (Bidirectional Recurrent..." Skipped: agentic-research/cloister — description already strong jamestexas/papers — no README signal, needs human input ``` ## Examples ``` /repo-description-polish agentic-research/mache → dry-run proposal for mache /repo-description-polish jamestexas/bread jamestexas/moat --apply → proposal for both, prompts for approval, writes via gh /repo-description-polish → uses current working directory's repo ``` ## Important rules - **Default to `--dry-run`.** Descriptions are visible to anyone, including the org page. - **One field per pass.** Do not bundle description changes with topic or homepage changes — that's the parent `repo-seo-curator`'s job to sequence. - **If a description is already strong, skip the repo.** Churn hurts SEO. - **Don't touch forks or archived repos** unless explicitly named. - **For private repos, ask before writing.** Even private descriptions are visible to org members in some surfaces; the user may want different copy than for public.