labels-as-code

Brings a single GitHub repository's labels under version control and keeps pull-request labeling in sync with the files that changed.

Where this skill fits

Concern	Skill
One repo's label set, tracked in a file, synced on demand or on schedule	`/labels-as-code` (this skill)
Path-based PR auto-labeling for one repo	`/labels-as-code` (this skill)
Label policy across many repos, reconciled from one admin repo	`/safe-settings`
Issue forms, PR templates, community health files	`/oss-hygiene`

/safe-settings

can also manage labels org-wide through its

labels

block (rename via

oldname

, exclusion patterns), reconciled every

full-sync

run. Reach for

/safe-settings

when label policy must stay in sync across many repos from a central admin repo. Reach for this skill when the scope is one repository and the file lives in that repository.

What gets configured

File	Purpose
`.github/labels.yml`	The label set: `name` , `color` , `description` per label
`.github/labeler.yml`	Path-to-label rules consumed by `actions/labeler`
`.github/workflows/labels-sync.yml` (optional)	Scheduled/on-push sync of `.github/labels.yml` to the repo
`.github/workflows/labeler.yml` (optional)	Runs `actions/labeler` on every pull request

Protocol

1. Export current labels and diff

bash

gh label list --json name,color,description

Compare the export against the proposed

.github/labels.yml

(create it from

assets/labels.yml

if the file does not exist yet). Print the diff — labels to create, labels to recolor or redescribe, and labels present on GitHub but absent from the file — before proposing any change.

2. Propose a default label set

assets/labels.yml

ships a starting set grouped by prefix:

```
type/*
```
— one label per Conventional Commits type (
```
feat
```
,
```
fix
```
,
```
docs
```
,
```
style
```
,
```
refactor
```
,
```
perf
```
,
```
test
```
,
```
build
```
,
```
ci
```
,
```
chore
```
,
```
revert
```
), aligned with the types
```
/pr-title-lint
```
checks in the PR title.
```
priority/*
```
—
```
critical
```
,
```
high
```
,
```
medium
```
,
```
low
```
.
```
status/*
```
—
```
blocked
```
,
```
in-progress
```
,
```
needs-review
```
.
```
good first issue
```
,
```
help wanted
```
— GitHub's own community-standards labels.
```
dependencies
```
— Dependabot and manual dependency-bump PRs.
```
breaking
```
— a breaking change, called out at release time.

Read

references/label-scheme.md

for the full table and for how

type/*

and

breaking

map onto

/gh-bootstrap

.github/release.yml

categories (that file's

Breaking changes

bucket keys on

breaking-change

breaking

; its

Features

Fixes

Documentation

Internal

buckets key on bare Conventional-Commits-style names, not the

type/

prefix). If the repo already runs

/gh-bootstrap

's release notes, either keep both label spellings on the affected PRs or extend

release.yml

's category lists with the

type/*

names —

/gh-bootstrap

owns that file; this skill only documents the mapping.

Ask the user whether to adopt the default set as-is, trim it, or start from the exported labels instead. Do not assume — a repo with an established label set may prefer to keep its own names.

3. Sync options

Two ways to apply

.github/labels.yml

to the repo. Ask the user which one before doing either.

The workflow templates in this step and in step 4 pin Node 24 actions. Before you copy either workflow, confirm that any self-hosted runner is Actions Runner v2.327.1 or later. GitHub-hosted runners already meet this requirement.

One-shot sync

bash

# Create or update one label (never deletes):
gh label create "<name>" --color "<hex>" --description "<text>" --force

# Clone another repo's full label set (adds only; existing labels keep
# their color/description unless the label doesn't exist yet):
gh label clone <owner>/<repo>

--force

overwrites color/description on an existing label; it does not delete labels that are absent from the source. Never delete a label without explicit, per-label user authorization — list the labels that would be removed and wait for a yes before running

gh label delete

Scheduled sync workflow

For drift correction without a human running

gh label create

by hand, copy

assets/labels-sync.yml

.github/workflows/labels-sync.yml

. It runs

crazy-max/ghaction-github-labeler

, the maintained action verified for this skill (see

references/label-scheme.md

for the verification command and the current pinned SHA). The template ships with

skip-delete: true

— labels absent from

.github/labels.yml

are left alone, not deleted. Flip

skip-delete

false

only after the user explicitly authorizes deletions; the diff in step 1 shows exactly which labels that would remove. The template runs weekly on a

schedule

trigger, on each push to

main

that changes

.github/labels.yml

or the workflow file itself, and on manual

workflow_dispatch

EndBug/label-sync

is a viable alternative with the same shape (sync from a YAML file, delete-by-default gated by an option). Verify either action's latest release and SHA with

gh api repos/{owner}/{repo}

and the tag-to-commit lookup in

references/label-scheme.md

before pinning — do not reuse a SHA from this skill without re-verifying it against the current release.

4. Path-based PR labeling

Copy

assets/labeler.yml

.github/labeler.yml

and adapt the path globs to the repo's directory layout — the shipped file is an example, not a fit-all config. Copy

assets/pr-labeler.yml

.github/workflows/labeler.yml

; it runs

actions/labeler

with

permissions: contents: read, pull-requests: write

(the minimum the action needs to read changed files and write labels).

Verify the pinned SHA before relying on it:

bash

LATEST=$(gh api repos/actions/labeler/releases/latest --jq '.tag_name')
gh api repos/actions/labeler/git/ref/tags/"$LATEST" --jq '.object.sha'

If the returned SHA does not match the comment in

assets/pr-labeler.yml

, update both the

uses:

line and its trailing version comment together — a stale comment next to a fresh SHA is worse than no comment.

5. Verify

bash

gh label list --json name,color,description

Confirm the output matches

.github/labels.yml

exactly (same names, colors, descriptions — modulo any labels the user chose to keep unmanaged). Then open a pull request that touches a path matched in

.github/labeler.yml

and confirm the expected label lands on it, either by watching the

labeler.yml

run or with:

bash

gh pr view <number> --json labels --jq '.labels[].name'

Report what was created, updated, and left alone, and which labels (if any) are still pending user authorization to delete.

What this skill is NOT for

Org-wide label policy reconciled across many repos — use
```
/safe-settings
```
Issue forms, PR templates, or other community-health files — use
```
/oss-hygiene
```
Deleting labels without the user's explicit, per-label go-ahead
Branch protection, merge settings, or release-notes plumbing — use
```
/gh-bootstrap
```

Gotchas

```
gh label create --force
```
is idempotent for color/description but never deletes. Deletion is a separate, explicit
```
gh label delete
```
call — never bundle it into a routine sync without asking first.
```
crazy-max/ghaction-github-labeler
```
deletes labels that are absent from the YAML file unless
```
skip-delete: true
```
is set. Confirm that flag before wiring the workflow into a repo with labels the file doesn't enumerate.
```
actions/labeler
```
's
```
sync-labels
```
input removes a path-based label when the PR no longer touches that path. Leave it at its default (
```
false
```
) unless the user wants that behavior — it is a form of automatic deletion.
Label colors in
```
gh label create --color
```
take a bare hex string without
```
#
```
;
```
.github/labels.yml
```
conventionally also stores the hex without
```
#
```
for
```
actions/labeler
```
's upstream ecosystem, but
```
crazy-max/ghaction-github-labeler
```
accepts either. Keep one convention within a repo's file.
Renaming a label with
```
gh label create --force
```
does not rename — it creates a new label. Use
```
gh label edit <old-name> --name <new-name>
```
for renames, or
```
from_name:
```
in the sync tool's config format if it supports it.

labels-as-code

NPX Install

Tags

SKILL.md Content

labels-as-code

Where this skill fits

What gets configured

Protocol

1. Export current labels and diff

2. Propose a default label set

3. Sync options

One-shot sync

Scheduled sync workflow

4. Path-based PR labeling

5. Verify

What this skill is NOT for

Gotchas