# Skill: GitHub Labels
A Claude Code skill that sets up a structured label taxonomy on any GitHub repo — priority, clarity, risk, blast radius, and more.

category: Skill
date: Sun Apr 12 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
reading-time: 6 min read
excerpt: A companion to Workflow, April 2026 — this is a runnable Claude Code skill that sets up the full label taxonomy from that article on any GitHub repo. Pick the groups you need, run the skill, and your issues speak a language that both humans and AI agents understand.

---



# GitHub Labels Skill

This skill implements the label taxonomy described in [Workflow, April 2026](/writing/working-april-26). Install it on any GitHub repository using `gh label create`.

## Prerequisites

- `gh` CLI installed and authenticated (`gh auth status` should succeed)
- Write access to the target repository

## How it works

1. Ask the user which repository to target (owner/repo format, or auto-detect from current git remote)
2. Present the available label groups and ask which ones to install
3. Create each label via `gh label create` with `--force` (upserts — safe to re-run)

## Label Groups

Present these groups to the user. Let them pick individually or say "all" for everything.

### 1. Priority (`priority`)

Triage priority — what ships first.

| Label | Color | Description |
|-------|-------|-------------|
| `P1` | `#b60205` | Must ship first, blocks other work |
| `P2` | `#d93f0b` | Core features, ship after P1 |
| `P3` | `#e99695` | Polish and low-urgency items |
| `P4` | `#f9d0c4` | Post-launch polish and enhancements |
| `P5` | `#fef2c0` | Nice to have, no pressure |

### 2. Clarity (`clarity`)

How well-defined is the issue? Drives whether it needs a spike or is ready to build.

| Label | Color | Description |
|-------|-------|-------------|
| `clarity:1` | `#5319e7` | Vague idea — no spec, no definition of done, needs discussion |
| `clarity:2` | `#7b61ff` | Problem defined, solution unclear — needs a design spike |
| `clarity:3` | `#a78bfa` | Direction known, details TBD — can start with questions |
| `clarity:4` | `#c4b5fd` | Clear spec, minor ambiguities — AI-shippable with light review |
| `clarity:5` | `#ddd6fe` | Crystal clear, full definition of done — just execute |

### 3. Risk (`risk`)

How dangerous is this change? Higher = more review and testing needed.

| Label | Color | Description |
|-------|-------|-------------|
| `risk:1` | `#0e8a16` | Isolated change, well-tested area, hard to break |
| `risk:2` | `#53d353` | Small surface area, existing patterns, minor regression chance |
| `risk:3` | `#fbca04` | Touches shared code, some edge cases, needs careful testing |
| `risk:4` | `#e99695` | Cross-domain impact, state management, concurrency concerns |
| `risk:5` | `#b60205` | Data model migration, navigation architecture, or seed data changes |

### 4. Blast Radius (`blast`)

How many files/domains does this touch?

| Label | Color | Description |
|-------|-------|-------------|
| `blast:1` | `#bfdadc` | Single file — one view or one service, no ripple effects |
| `blast:2` | `#7ec8cb` | Single domain — 2-5 files within one feature folder |
| `blast:3` | `#3bb3b8` | Cross-domain — touches shared code or 2+ feature domains |
| `blast:4` | `#1d7a7e` | Architectural — services, navigation, data flow changes |
| `blast:5` | `#0e4f52` | Full-stack — data pipeline + app, or schema changes |

### 5. Size (`size`)

T-shirt sizing for effort estimation.

| Label | Color | Description |
|-------|-------|-------------|
| `size:XS` | `#c5def5` | Trivial change, single file |
| `size:S` | `#85c1e9` | Straightforward, few files |
| `size:M` | `#5dade2` | Moderate scope, some design needed |
| `size:L` | `#2e86c1` | Significant feature, many files |
| `size:XL` | `#1a5276` | Epic-level, major cross-cutting work |

### 6. Parallelism (`parallelism`)

Lane-based work distribution — which issues can run concurrently.

| Label | Color | Description |
|-------|-------|-------------|
| `parallel:1` | `#f0e68c` | Lane 1 work stream |
| `parallel:2` | `#daa520` | Lane 2 work stream |
| `parallel:3` | `#cd853f` | Lane 3 work stream |
| `parallel:4` | `#b8860b` | Lane 4 work stream |
| `parallel:5` | `#8b6914` | Lane 5 work stream |
| `serial` | `#6c757d` | Cross-cutting — touches 2+ lanes, run alone |

### 7. Sequencing (`sequencing`)

Implementation order within a milestone or epic.

| Label | Color | Description |
|-------|-------|-------------|
| `seq:01` | `#006b75` | Sequence step 1 |
| `seq:02` | `#006b75` | Sequence step 2 |
| `seq:03` | `#006b75` | Sequence step 3 |
| `seq:04` | `#006b75` | Sequence step 4 |
| `seq:05` | `#006b75` | Sequence step 5 |
| `seq:06` | `#006b75` | Sequence step 6 |
| `seq:07` | `#006b75` | Sequence step 7 |
| `seq:08` | `#006b75` | Sequence step 8 |
| `seq:09` | `#006b75` | Sequence step 9 |
| `seq:10` | `#006b75` | Sequence step 10 |

### 8. Type (`type`)

What kind of work is this? Tells agents (and humans) which approach to take.

| Label | Color | Description |
|-------|-------|-------------|
| `type:bug` | `#d73a4a` | Something isn't working correctly |
| `type:feature` | `#0075ca` | New functionality or capability |
| `type:refactor` | `#cfd3d7` | Code improvement, no behaviour change |
| `type:chore` | `#ededed` | Maintenance — deps, CI, config, docs |
| `type:spike` | `#d4c5f9` | Research or time-boxed exploration |

### 9. Special (`special`)

Workflow flags that don't fit a scale.

| Label | Color | Description |
|-------|-------|-------------|
| `ai-shippable` | `#1d76db` | Delegatable to AI agents — clarity:4+ and risk:2 or lower |
| `needs-design` | `#d4c5f9` | Requires design work before implementation |

## Execution

For each selected group, run `gh label create` for every label in that group:

```bash
gh label create "<name>" --color "<hex without #>" --description "<description>" --repo "<owner/repo>" --force
```

The `--force` flag means this is idempotent — running it again updates existing labels rather than erroring.

## Interaction Flow

1. **Detect repo**: Check `gh repo view --json nameWithOwner -q .nameWithOwner` from the current directory. If it works, offer it as the default. Otherwise ask.

2. **Present groups**: Show the user a numbered list:
   ```
   Available label groups:
     1. Priority (P1-P5) — triage priority
     2. Clarity (clarity:1-5) — issue definition quality
     3. Risk (risk:1-5) — change danger level
     4. Blast Radius (blast:1-5) — scope of impact
     5. Size (size:XS-XL) — effort estimation
     6. Parallelism (parallel:1-5 + serial) — lane assignment
     7. Sequencing (seq:01-10) — implementation order
     8. Type (type:bug, feature, refactor, chore, spike) — work category
     9. Special (ai-shippable, needs-design) — workflow flags

   Enter numbers (e.g. "1,3,4"), "all", or ask me about any group.
   ```

3. **Confirm**: Show the total label count and target repo, ask for confirmation.

4. **Execute**: Create labels, reporting progress. Group output by category.

5. **Summary**: Report what was created/updated, note any failures.