Skip to content
Skills Library
Management & product · Planning

github-issue-management

/github-issue-management

Manage GitHub Issues using a structured label taxonomy (epic/story/bug), triage new issues, apply labels per strategy, maintain project board membership, and keep issues organised across one or more repos. Use when creating issues, triaging unlabelled issues, updating labels, managing milestones, or checking board consistency.

Licence
MIT
Last repository change
13.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/Set-IssueLabelExample.ps1

What it does and when to use it

Manage GitHub Issues using a structured label taxonomy (epic/story/bug), triage new issues, apply labels per strategy, maintain project board membership, and keep issues organised across one or more repos. Use when creating issues, triaging unlabelled issues, updating labels, managing milestones, or checking board consistency.

Original author description

Manage GitHub Issues using a structured label taxonomy (epic/story/bug), triage new issues, apply labels per strategy, maintain project board membership, and keep issues organised across one or more repos. Use when creating issues, triaging unlabelled issues, updating labels, managing milestones, or checking board consistency.

How it works

  1. When to use this skill
  2. How this skill is organised
  3. Core Workflow
  4. Creating Issues
  5. Triage Workflow
  6. Consistency Checks
Original SKILL.md headings · 140 lines, 807 words
SKILL.md preview
---
name: github-issue-management
description: Manage GitHub Issues using a structured label taxonomy (epic/story/bug), triage new issues, apply labels per strategy, maintain project board membership, and keep issues organised across one or more repos. Use when creating issues, triaging unlabelled issues, updating labels, managing milestones, or checking board consistency.
license: MIT
metadata:
  author: Mark Heydon
  version: "1.0"
compatibility: Requires GitHub CLI (gh) and GitHub API access. A .github/copilot-instructions.md may optionally be present in the target repo; if it exists, read it for repo-specific overrides.
---

# GitHub Issue Management Skill

This skill helps you manage GitHub Issues consistently using a **three-tier label taxonomy**: `epic`, `story`, and `bug`. It covers triage, label application, project board management, and milestone organisation.

## When to use this skill

- Creating a new issue and unsure which label(s) to apply.
- Triaging a batch of unlabelled issues.
- Checking whether issues are correctly on (or missing from) the project board.
- Planning iterations by grouping stories under epics.
- Keeping label usage consistent across multiple repos.

## How this skill is organised

| File | Purpose |
|------|---------|
| This file | Core workflow instructions |
| [`references/github-labels.md`](references/github-labels.md) | Full label taxonomy (names, colours, purposes, decision rules) |
| [`references/project-setup.md`](references/project-setup.md) | Project board configuration, status rules, and board behaviour |
| [`references/CUSTOMISATION_GUIDE.md`](references/CUSTOMISATION_GUIDE.md) | How to adapt this skill for a different repo |
| [`assets/triage-workflow.md`](assets/triage-workflow.md) | Visual triage decision flow |
| [`scripts/Set-IssueLabelExample.ps1`](scripts/Set-IssueLabelExample.ps1) | Example PowerShell script for automating label application via GitHub CLI |

---

## Core Workflow

### 1. Always start with the label taxonomy

Before creating or labelling any issue, read [`references/github-labels.md`](references/github-labels.md). If a `.github/copilot-instructions.md` exists in the **target repo**, read it too - it may override label names or add repo-specific rules.

> **If you are operating in a repo other than `markheydon/github-workflows`**, check [`references/CUSTOMISATION_GUIDE.md`](references/CUSTOMISATION_GUIDE.md) to understand what to override.

### 2. Classify the issue

Every issue needs **exactly one** core label:

| If the issue is... | Apply label |
|--------------------|-------------|
| A large body of work grouping multiple tasks | `epic` |
| A feature, improvement, or technical task | `story` |
| Something broken or not working | `bug` |

Use the decision guide in [`references/github-labels.md`](references/github-labels.md) for edge cases.

### 3. Apply modifier labels (optional)

After the core label, assess whether any modifier labels apply. Multiple modifiers are allowed. See [`references/github-labels.md`](references/github-labels.md) for the full list.

Common combinations:
- `story` + `priority-high` - urgent new work.
- `story` + `blocked` - blocked waiting on another issue.
- `bug` + `priority-high` - urgent fix needed.
- `story` + `out-of-scope` - explicit backlog deferral.

### 4. Project board membership

Issues and PRs labelled `story` or `bug` belong on the project board. `epic` issues do **not** go on the board. See [`references/project-setup.md`](references/project-setup.md) for board configuration details and Status field rules.

### 5. Milestone and epic linkage

- Stories should be linked to a parent epic via a checklist item in the epic's description (e.g., `- [ ] #42 Short description`).
- Milestones are optional but recommended for grouping stories into iterations.

---

## Creating Issues

When creating a new issue, always:

1. Determine core label (`epic`, `story`, or `bug`).
2. Write a title that is specific and action-oriented.
3. Add relevant modifier labels.
4. For stories: link to the parent epic if one exists.
5. For epics: create a task list of planned child stories in the description.

### Story template

```markdown
## Context
Brief description of the background or problem this addresses.

## What needs to happen
Clear description of the work to be done.

## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Parent Epic
Closes #<epic-number> (if applicable)
```

### Bug template

```markdown
## What happened
Clear description of the unexpected behaviour.

## Steps to reproduce
1. Step 1.
2. Step 2.

## Expected behaviour
What should have happened.

## Environment
Relevant version/environment info.
```

---

## Triage Workflow

When triaging a batch of unlabelled issues:

1. Read each issue title and body.
2. Classify as `epic`, `story`, or `bug` using the decision guide.
3. Apply the core label and any appropriate modifiers.
4. If the issue is clearly `story` or `bug`, check it should be on the project board.
5. Flag any issues that need more information before classification - apply `waiting-for-details`.
6. Summarise what was triaged and highlight anything requiring human review.

**Watch for disguised epics.** An issue labelled `story` may actually be an epic if it: has multiple sub-issues listed, describes a large feature with its own data model or architecture section, or has an acceptance criteria list that spans several independent deliverables. If so, relabel it `epic`, remove it from the project board, and ensure its sub-issues are individually labelled and have appropriate statuses (e.g. `blocked` if they depend on each other sequentially).

For a visual flow, see [`assets/triage-workflow.md`](assets/triage-workflow.md).

---

## Consistency Checks

When asked to validate issue/label consistency:

1. List all open issues without a core label (`epic`, `story`, or `bug`) - these need triage.
2. List all issues labelled `story` or `bug` that are **not** on the project board - these need adding.
3. List all issues labelled `epic` that **are** on the project board - these need removing.
4. Report any labels in use that are not in the approved taxonomy.
5. Summarise findings and ask whether to auto-fix.
Files in this package (6)
  • SKILL.md 6 KB
  • assets/triage-workflow.md 2 KB
  • references/CUSTOMISATION_GUIDE.md 3 KB
  • references/github-labels.md 4 KB
  • references/project-setup.md 3 KB
  • scripts/Set-IssueLabelExample.ps1 2 KB

Versions

The database has no other skills named github-issue-management.

Database snapshot: 13.11.2026 · package version f2ec6f71e6a7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100glab-issue
    Create, view, update, and manage GitLab issues. Use when working with issue tracking, bug reports, feature requests, or task management. Operations include creating issues, listing with filters, viewing details, adding comments/notes, updating labels/assignees/milestones,…
  • 100github-issue-triage
    Triage GitHub issues: list what is open or unlabelled, read issues, suggest labels from the repository's own and a priority, and find duplicates, open or closed, without changing anything unless asked. Use when the user asks what is open or unlabelled in a GitHub repository, to…
  • 100github-issues
    Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue",…
  • 100project-manager
    Use this skill for ANY interaction with external issue tracking and project management tools (Linear, Jira, GitHub Issues, etc.). This includes: - Reading, creating, or updating issues in Linear/Jira/GitHub - Querying project boards, backlogs, or sprints - Updating issue…
  • 100github-labels
    GitHub label taxonomy for kookr-ai/kookr. Use when creating issues, PRs, or triaging work to apply correct labels.
  • 100issues-and-roadmap
    Use when planning work on a GitHub repo, such as milestones, a roadmap, a project board or sizes, when writing an issue someone else should be able to pick up, including good first issues and "writers wanted", when setting issue types, sub-issues or blocked-by links, or when…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.