Managing Repository Labels

Analyze repository context and establish or refresh a semantic label system tailored to the project's domain and needs.

What you should do

When invoked, help the user create or refresh their repository's label system by:

1. •

   Understanding the request - Determine what's needed:

   • •Initial setup for new repository
   • •Periodic refresh (6-12 month cycle)
   • •Standardization across organization
   • •Migration from legacy labels
2. •

   Analyzing the repository - Gather context:

   • •Technology stack and project type
   • •Existing issue patterns
   • •Current label usage and gaps
   • •Team terminology
3. •

   Designing the label system - Create semantic labels:

   • •Core categories (bug, enhancement, question)
   • •Domain-specific labels (api, frontend, pipeline, etc.)
   • •Apply semantic color philosophy
   • •Ensure no redundancy or overlap
4. •

   Implementing changes - Execute carefully:

   • •Create new labels with proper colors
   • •Migrate issues from old to new labels
   • •Delete obsolete labels (after verification)
   • •Audit and label unlabeled issues
5. •

   Documenting the system - Create .github/LABELS.md:

   • •Label categories and descriptions
   • •Usage guidelines
   • •Migration history

When to use this skill

Trigger phrases:

• •"Set up labels"
• •"Organize our labels"
• •"Label system is a mess"
• •"Standardize labels"
• •"Clean up labels"
• •"Refresh label system"

Proactive detection:

• •Many unlabeled issues detected
• •Duplicate labels observed (e.g., docs and documentation)
• •Inconsistent label usage
• •Project scope has expanded
• •Team mentions label confusion

Scheduled maintenance:

• •Every 6-12 months for active repositories
• •When merging multiple repositories
• •After significant project evolution

Analysis process

1. Analyze repository context

# Get repository information
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
REPO_DESCRIPTION=$(gh repo view --json description -q .description)

# List existing labels
gh label list --json name,description,color --limit 100

# Analyze recent issues for patterns
gh issue list --limit 50 --json title,body,labels --state all

Look for:

• •Technology stack (languages, frameworks)
• •Issue patterns (security, performance, bugs, features)
• •Team terminology (what words do they use?)
• •Missing label coverage (unlabeled issues)

2. Determine label categories

Core categories (most repositories need):

• •Nature: bug, enhancement, question
• •Domain-specific: Labels specific to project type (api, frontend, backend)
• •Quality: testing, refactor, docs
• •Infrastructure: ci, dependencies, config
• •Impact: security, performance, accessibility

Important: Do NOT create labels for status (todo/done), priority (high/low), value (essential/nice-to-have), or effort (heavy/light). These should be managed as custom fields in GitHub Projects V2, not labels.

Repository-specific examples:

• •API project: endpoint, schema, authentication
• •Data project: pipeline, validation, data-quality
• •UI project: ux, accessibility, design-system
• •Library: breaking-change, deprecation, api

Color assignment

Use semantic color philosophy to communicate meaning visually. See LABEL-COLORS.md for complete reference.

Quick reference

Color selection rules

1. •Darker shades = higher urgency within same color family
2. •Never use pure red (FF0000) - too alarming
3. •Limit to 2-3 shades per color family - avoid confusion
4. •Test accessibility - ensure WCAG AA contrast
5. •Match GitHub defaults - bug uses FF3B30

Implementation workflow

Step 1: Create or update labels

# Create new labels
gh label create "bug" --description "Something isn't working" --color "FF3B30"

# Update existing labels
gh label edit "bug" --description "Something isn't working" --color "FF3B30"

Step 2: Migrate issues

Before deleting obsolete labels, migrate issues:

# List issues with old label
OLD_LABEL="old-label-name"
NEW_LABEL="new-label-name"

ISSUES=$(gh issue list --label "$OLD_LABEL" --json number --jq '.[].number')

# Migrate each issue
for issue in $ISSUES; do
  echo "Migrating issue #$issue from $OLD_LABEL to $NEW_LABEL"
  gh issue edit $issue --remove-label "$OLD_LABEL" --add-label "$NEW_LABEL"
done

Migration strategies:

• •Direct replacement: Old label → New label (1:1)
• •Split: One old → Multiple new (e.g., feature → enhancement + domain)
• •Consolidate: Multiple old → One new (e.g., high-priority + critical → security)
• •Drop: Remove obsolete labels

Step 3: Clean up obsolete labels

After migration, delete old labels:

# Verify label has no remaining issues
REMAINING=$(gh issue list --label "old-label" --json number --jq 'length')

if [ "$REMAINING" -eq 0 ]; then
  gh label delete "old-label"
  echo "Deleted obsolete label: old-label"
else
  echo "Warning: $REMAINING issues still use old-label"
fi

Common labels to clean up:

• •Status labels: todo, in-progress, done, backlog (use Status custom field)
• •Priority labels: high-priority, low-priority, p0, p1 (use Value/Effort custom fields)
• •Value labels: essential, nice-to-have (use Value custom field)
• •Effort labels: heavy, light, quick-win (use Effort custom field)
• •Duplicate labels (e.g., documentation and docs)
• •Vague labels (e.g., needs-work, help-wanted)
• •Legacy project-specific labels

Step 4: Audit unlabeled issues

# Find unlabeled issues
gh issue list --label "" --limit 100 --json number,title

# Review and apply appropriate labels
for issue in $(gh issue list --label "" --json number --jq '.[].number' | head -20); do
  gh issue view $issue
  # gh issue edit $issue --add-label "appropriate-label"
done

Step 5: Document the system

Create or update .github/LABELS.md:

# Repository Labels

## Label Categories

### Critical Issues (Red-Orange)
- `bug` - Something isn't working
- `security` - Security-related issues
- `performance` - Performance improvements

### Quality (Green)
- `testing` - Test suite improvements
- `docs` - Documentation updates

### Infrastructure (Blue-Cyan)
- `ci` - Continuous integration
- `dependencies` - Dependency updates

## When to Use

**bug**: Broken functionality, errors, or unexpected behavior
**security**: Any security vulnerability or concern
**testing**: Test suite or testing infrastructure changes
**docs**: Documentation improvements

## Multiple Labels

Issues can have multiple labels:
- `bug` + `security`: Security vulnerability
- `enhancement` + `performance`: Performance-improving feature

## Migration History

### YYYY-MM-DD: Label system refresh
- **Reason**: [Initial setup | Periodic refresh | Project scope expansion]
- **Changes made**:
  - Migrated `feature` → `enhancement`
  - Consolidated `high-priority`, `urgent` → `security`
  - Deleted obsolete labels: `wontfix`, `invalid`
  - Added domain labels: `api`, `frontend`, `backend`
- **Issues affected**: XX issues migrated

**Maintenance schedule:**
- Review label system every 6-12 months
- Document each refresh with date and reason
- Update this file when label changes are made

Quality gates

Before completing, verify:

• • Labels cover all common issue types in repository
• • Colors follow semantic color philosophy
• • Descriptions are clear and actionable
• • No redundant or overlapping labels
• • All issues migrated from old to new labels
• • Obsolete labels verified empty and deleted
• • Documentation created in .github/LABELS.md with migration history
• • Unlabeled issues reviewed and labeled appropriately

Expected outcomes

• •Consistent label system aligned to repository needs
• •Semantic colors that communicate priority/type visually
• •Clear documentation for contributors
• •Existing issues properly categorized
• •Foundation for better issue triage and project management
• •Maintenance schedule established

Repository type examples

API/Backend project

• •api, endpoint, database, authentication
• •bug, security, performance
• •testing, docs, ci

Frontend project

• •ui, ux, accessibility, design-system
• •bug, browser-compat, performance
• •testing, docs, dependencies

Data/Pipeline project

• •pipeline, validation, data-quality
• •bug, performance, config
• •testing, docs, dependencies

Library/Framework

• •api, breaking-change, deprecation
• •bug, enhancement, docs
• •examples, testing, dependencies

Integration with other skills

Works with:

• •gh-project-setup - Use during initial project setup
• •git-issue-create - References label system for new issues
• •gh-project-manage - Complements project field management

Triggers from:

• •Repository onboarding workflows
• •Project setup automation
• •Issue creation detecting missing labels
• •Team requesting better organization