Issue Triage Skill

Label, deduplicate, and prioritize GitHub issues automatically using configurable heuristics.

issuestriagegithubproject-management

Issue Triage Skill

TL;DR

The Issue Triage skill monitors your GitHub (or GitLab/Linear) issue tracker, classifies new issues by type and priority, detects duplicates, and applies labels — all without requiring a human to read every incoming report. For open-source projects receiving dozens of issues per week, or support teams managing a shared backlog, this skill can cut triage time by 60–80%.

The intermediate complexity rating reflects the setup work: you need to define your label taxonomy, priority heuristics, and duplicate detection thresholds before the skill produces reliable results. A poorly configured triage skill that mislabels issues or closes legitimate reports as duplicates creates more work than it saves.

What it does

  • Classifies new issues into types (bug, feature request, question, documentation, security) based on the issue title, body, and any template fields the reporter filled in.
  • Assigns priority labels (P0–P3 or Critical/High/Medium/Low) using heuristics: crash reports get higher priority than cosmetic issues; issues from paying customers or VIP reporters get escalated.
  • Detects duplicate issues by comparing new issues against open and recently-closed issues using semantic similarity — not just exact keyword matching.
  • Requests missing information by posting a comment when a bug report lacks reproduction steps, environment details, or expected vs. actual behavior.
  • Routes issues to the right team by applying component labels (e.g., area/auth, area/billing, area/docs) based on the affected feature area.
  • Generates a weekly triage digest summarizing new issues by type, priority, and component — useful for sprint planning and backlog grooming.

Best for

Open-source project maintainers: When your project has more incoming issues than you have time to read, the skill handles the mechanical triage so you can focus on the issues that actually need your expertise.

SaaS support teams: Route incoming bug reports to the right engineering team automatically, request reproduction steps from reporters who skipped the template, and flag potential security issues for immediate escalation.

Product backlog management: Keep your backlog organized by automatically labeling feature requests by product area, priority, and effort estimate — making sprint planning faster and more consistent.

Duplicate reduction: In active projects, the same bug gets reported multiple times. The skill detects semantic duplicates (not just identical titles) and links them, keeping your issue count accurate and preventing duplicate work.

How to use (example)

Scenario: Triaging issues for an open-source CLI tool

Your CLI tool receives 20–30 new issues per week. You want automatic labeling, duplicate detection, and a request for missing info on incomplete bug reports.

Label taxonomy:

type_labels:
  - "bug"
  - "feature-request"
  - "question"
  - "documentation"
  - "security"

priority_labels:
  - "P0-critical"    # Crash, data loss, security vulnerability
  - "P1-high"        # Core feature broken, no workaround
  - "P2-medium"      # Feature degraded, workaround exists
  - "P3-low"         # Cosmetic, nice-to-have

component_labels:
  - "area/install"
  - "area/config"
  - "area/output"
  - "area/performance"

Priority heuristics:

escalate_to_P0_if:
  - title_contains: ["crash", "panic", "data loss", "security", "CVE"]
  - body_contains: ["segfault", "null pointer", "corrupted"]

escalate_to_P1_if:
  - title_contains: ["broken", "not working", "fails", "error"]
  - reporter_has_label: "vip-customer"

Example: Incoming bug report

Issue title: “CLI crashes when config file has unicode characters”

Skill actions:

  1. Classifies as bug (crash language detected).
  2. Assigns P0-critical (crash + “crashes” keyword).
  3. Applies area/config (config file mentioned).
  4. Checks for duplicates — finds a similar closed issue from 3 months ago, links it.
  5. Checks for reproduction steps — present, no comment needed.
  6. Posts labels and a comment: “Linked to #234 (similar issue, previously closed as fixed — may have regressed).”

Common variations:

  • Add auto_close_duplicates: false to link duplicates without closing them — safer for active issues.
  • Use request_info_template to customize the comment posted when reproduction steps are missing.
  • Combine with release notes to automatically include triaged bugs in the next changelog.

Permissions & Risks

Required permissions: Repo API (read issues, write labels, write comments)
Risk level: Low

The skill reads issues and writes labels and comments — it doesn’t close issues, delete content, or modify code. The main risks are operational:

Duplicate detection accuracy: Semantic similarity matching isn’t perfect. Two issues that sound similar may describe different root causes; two issues with different titles may be the same bug. Set a similarity_threshold (e.g., 0.85) and review flagged duplicates before auto-closing. Start with flag_only mode rather than auto-closing.

Priority misassignment: A P0 label on a minor cosmetic issue creates false urgency; a P3 label on a real crash causes it to be ignored. Tune your heuristics on a sample of historical issues before enabling automated priority assignment.

Label taxonomy drift: As your project evolves, labels get added, renamed, or deprecated. The skill’s classification rules need to stay in sync with your actual label set. Schedule a quarterly review of your label taxonomy and update the skill configuration accordingly.

Recommended guardrails:

  • Run in dry_run: true mode for the first two weeks, reviewing what the skill would have done without actually applying labels.
  • Never auto-close issues as duplicates without a human review step — a false duplicate close frustrates reporters and loses real bug reports.
  • Log every triage decision with the reasoning so you can audit and improve the heuristics.

Troubleshooting

Skill is labeling feature requests as bugs
Your type classification heuristics are too broad. Add negative signals: if the issue body contains “would be great if” or “I’d love to see,” it’s almost certainly a feature request even if it also mentions something “not working.”

Duplicate detection is flagging unrelated issues
Your similarity threshold is too low. Raise it from 0.75 to 0.85 or higher. Also check whether the skill is comparing against closed issues from too far back — limit duplicate search to issues closed in the last 90 days.

“Missing info” comments are being posted on complete bug reports
Your required fields checklist doesn’t match what reporters are actually providing. Update the checklist to match your issue template fields exactly, and add flexibility for reporters who provide the information in a non-standard format.

Labels aren’t being applied despite the skill running
Check the API token permissions. The token needs issues: write scope on GitHub. A read-only token will silently fail to apply labels without returning an error in some API versions.

Skill is missing security-related issues
Security issues often use indirect language (“unexpected behavior when…”) rather than explicit keywords. Add a separate security detection pass that looks for patterns like “arbitrary code execution,” “authentication bypass,” “privilege escalation,” and routes them to a private security channel rather than the public issue tracker.

Alternatives

GitHub Actions + labeler — The official GitHub actions/labeler action applies labels based on file paths changed in PRs, not issue content. Useful for PR labeling; not designed for issue classification or duplicate detection.

Linear’s auto-triage — Linear has built-in AI triage features for teams using Linear as their issue tracker. Tighter integration with Linear’s workflow; not applicable if you’re using GitHub Issues or Jira.

Manual triage rotation — Assign a rotating “triage duty” role to team members who review and label new issues each week. Zero false positives; requires team time and consistent application of labeling rules. The right choice for small teams or projects where issue quality is highly variable.

Links & sources

  • GitHub Issues API: docs.github.com/en/rest/issues
  • GitHub Labels API: docs.github.com/en/rest/issues/labels
  • Related guide: Best Skills for Developers

Related Skills

Explore more AI skills in our directory.

Back to Skills