elevanaltd/github-labels

GitHub Labels Skill

Purpose

Prevents "label not found" errors when creating GitHub issues by providing agents with the current valid label taxonomy.

Valid Labels (Current Repository)

Standard Labels

• bug - Something isn't working
• documentation - Improvements or additions to documentation
• duplicate - This issue or pull request already exists
• enhancement - New feature or request
• good first issue - Good for newcomers
• help wanted - Extra attention is needed
• invalid - This doesn't seem right
• question - Further information is requested
• wontfix - This will not be worked on

Document Types

• adr - Architecture Decision Record
• rfc - Request for Comments (deprecated per ADR-0060)

Priority Levels

• priority:p0-critical - Blocking production or critical path
• priority:p1-high - Important, should be addressed soon
• priority:p2-medium - Normal priority
• priority:p3-low - Nice to have

Development Phases

• phase:b1 - B1: Foundation phase
• phase:b2 - B2: Features phase
• phase:future - Future consideration

Area Tags

• area:mcp-tools - MCP tool implementation
• area:governance - Governance system
• area:ci-cd - CI/CD pipeline
• area:agents - Agent system

Status Tags

• status:blocked - Blocked by dependencies
• status:needs-discussion - Needs team discussion
• status:implementation-pending - Approved, waiting for implementation
• status:draft - Draft/work in progress
• obsolete - No longer relevant

Milestone Tags

• milestone:b1-foundation - B1 milestone
• milestone:b2-features - B2 milestone
• milestone:b3-integration - B3 milestone

Special Tags

• epic - Epic tracking issue
• octave-integration - OCTAVE integration work

Usage Pattern

Before creating a GitHub issue:

# 1. Verify current labels (labels can change over time)
gh label list --json name --jq '.[].name'

# 2. Create issue with ONLY valid labels
gh issue create \
  --title "Issue Title" \
  --label "enhancement,priority:p2-medium,phase:b1" \
  --body "Issue description"

Common Mistakes to Avoid

❌ Don't use:

• p0, p1, p2, p3 (missing priority: prefix)
• b1, b2 (missing phase: prefix)
• mcp-tools, governance (missing area: prefix)
• Custom labels that don't exist

✅ Do use:

• priority:p0-critical, priority:p1-high
• phase:b1, phase:b2
• area:mcp-tools, area:governance
• Exact label names from the valid list above (including spaces when present, e.g., good first issue)

Auto-Validation

The ~/.claude/hooks/pre_tool_use/validate-gh-labels.sh hook automatically:

1. Intercepts Bash tool before gh issue create executes
2. Validates labels against current repository labels (cached 5min)
3. Removes invalid labels
4. Warns you about changes

If you see a warning, check this skill for the correct label names.

Dynamic Label Lookup

To get the current label list programmatically:

gh label list --json name,description --jq '.[] | "\(.name): \(.description)"'

Integration with Hooks

This skill works in tandem with the label validation hook to:

• Prevent errors before they happen
• Save time by avoiding re-writes
• Educate agents about valid taxonomy

Escalation

If you need a new label that doesn't exist:

1. Discuss with the team first
2. Create label via: gh label create <name> --description "..." --color <hex>
3. Update this skill documentation