Manage Issues

Managing GitHub Issues

Manage the active repository's issue tracker via gh. Every issue must be self-contained, professional, and actionable without prior context. The skill applies only to repositories where Issues are enabled; if ISSUES_ENABLED is false in the taxonomy, stop and tell the user.

Running scripts bundled with this skill

Script paths in this document (e.g. scripts/) are resolved relative to this SKILL.md file, not to your current working directory. If a relative command fails to resolve, prefix it with the path your platform loaded this SKILL.md from.

Fallback. If the script cannot be located, run the equivalent gh commands listed at the end of "Discover taxonomy" below; the script is a convenience wrapper around the same calls. If gh itself is missing or unauthenticated, the skill cannot proceed: surface the error to the user and stop.

Discover taxonomy (run first)

Before any create, edit, or triage operation, fetch the live taxonomy for the active repo:

bash scripts/get_taxonomy.sh --cached

The output declares seven sections: CACHED_AT, REPO, ISSUES_ENABLED, ISSUE_TYPES, LABEL_PREFIXES, LABELS, MILESTONES, PROJECT_BOARDS. Use the values verbatim; never memorize or guess label names, milestone titles, type node_ids, or project names.

The --cached flag reads from a 24h file cache keyed by owner/repo under ${TMPDIR:-/tmp}/manage-issues-cache/. Re-run without --cached when:

• An Error recovery row matches a "not found" condition.
• The user added, renamed, or closed labels, milestones, or projects in this session.
• CACHED_AT is older than 24 hours.

Branching on what the taxonomy reports:

| Section reports | Behavior | |---|---| | ISSUES_ENABLED: false | Stop. Tell the user the repository does not use GitHub Issues. | | ISSUE_TYPES: (none) | Skip the issue-type assignment step; rely on labels for classification. | | LABEL_PREFIXES: (none; ...) | Use flat labels exactly as listed; do not invent prefix:value style. | | LABEL_PREFIXES: | Follow the detected convention. Pick at least one label that scopes the affected subsystem when such a prefix exists (typically area:). | | MILESTONES: (none open) | Omit --milestone everywhere. | | PROJECT_BOARDS: (none ...) | Omit --project everywhere. |

If the script is unavailable, the equivalent calls are:

gh repo view --json nameWithOwner,hasIssuesEnabled
gh api "/orgs/{owner}/issue-types"
gh label list --limit 200
gh api "repos/{owner}/{repo}/milestones?state=open" --paginate
gh project list --owner {owner} --limit 10

Issue Type assignment (only if configured)

If ISSUE_TYPES is non-empty, every issue must have exactly one type from that list. gh issue create does not accept --type, so set the type via GraphQL after creation:

ISSUE_NODE_ID=$(gh api "repos/{owner}/{repo}/issues/${ISSUE_NUMBER}" --jq '.node_id')
gh api graphql -f query="
mutation {
  updateIssue(input: {
    id: \"${ISSUE_NODE_ID}\"
    issueTypeId: \"\"
  }) {
    issue { number title }
  }
}"

If ISSUE_TYPES: (none), skip this step entirely. The repo uses labels, not GitHub Issue Types, for classification.

Milestone matching

The user may reference a milestone by full title or by shorthand specific to their project (M10, 2025Q4, v2.1, etc.).

1. List the full titles from the MILESTONES section of the taxonomy.
2. If the shorthand maps unambiguously to one full title (substring, leading token, prefix), use that exact full title in --milestone.
3. If multiple titles plausibly match, ask the user to disambiguate.
4. If the user did not name any milestone, pick the best-fitting open milestone based on the issue's theme. If none fits, omit --milestone rather than blocking or asking.

Before creating an issue

Duplicate check (BLOCKING)

gh issue list --search "" --state all --limit 20 \
  --json number,title,state,labels,milestone \
  --jq '.[] | "#\(.number) [\(.state)] \(.title)"'

• Exact duplicate. Stop. Report the existing issue number.
• Partial overlap. Mention the related issue. Ask whether to proceed.
• No match. Proceed.

Create

Body rules

• Language. English.
• Tone. Professional, concise, no filler.
• Privacy. Never include usernames, API keys, internal URLs, tokens, or personal information, regardless of whether the repository is public or private.
• Self-contained. A stranger must understand the issue from the body alone.
• Bugs describe problems, not solutions. The implementer chooses the fix.
• Verification. Required for Bug and Feature. Optional for Research, Docs, Refactor, Test (include when a concrete completion signal exists).
• No hard wrapping. Write each paragraph as a single line; GitHub handles word wrap at render time. Hard line breaks mid-sentence produce ragged diffs and noisy reflows.

Body templates

Pick the template for the chosen issue type (or, if ISSUE_TYPES: (none), the template matching the inferred kind of work). Load the matching ## section of [assets/issue-templates.md](assets/issue-templates.md):

| Kind of work | Section in assets/issue-templates.md | |-----------------|--------------------------------------| | Bug | ## Bug | | Feature | ## Feature | | Research | ## Research | | Docs | ## Docs | | Refactor / Test | ## Refactor / Test |

Drop bracketed [...] sections of the template that do not apply. Required sections (no brackets) stay.

Title rules

• Imperative mood, capitalize first word: "Add X", "Fix Y", "Implement Z".
• Backtick-wrap code identifiers: ` Add --host flag for HTTP bind address `.
• Under 80 characters, no trailing period.
• No [type] prefix when ISSUE_TYPES is configured (the type carries the classification). When ISSUE_TYPES: (none), match the title style already used in the repo (gh issue list --state all --limit 20); add a [type] prefix only when the repo's existing titles do.

Composing the command

Use single quotes for --body to prevent shell interpolation. Escape literal single quotes in the body with '\''.

ISSUE_URL=$(gh issue create \
  --title '' \
  --body '' \
  --label '' \
  --milestone '' \
  --project '')

ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')

Drop the --label, --milestone, or --project flags when the corresponding taxonomy section is (none). After creation, run the GraphQL updateIssue mutation from "Issue Type assignment" if and only if ISSUE_TYPES is configured.

Batch creation

When creating multiple related issues:

1. Present all planned issues as a numbered list (title, type if applicable, labels, milestone) before creating any.
2. Wait for user confirmation.
3. Create sequentially. Report each issue number after creation.
4. Print a summary table when done:

| # | Title | Type | Labels | Milestone |
|---|-------|------|--------|-----------|

Search, Edit, Close

gh invocations for these three operations are catalogued in [references/gh-recipes.md](references/gh-recipes.md). Load that file when the user asks to find, modify, or close an issue. The rules below are policy and bind regardless of which recipe is used:

• Edit. Confirm destructive edits (body replacement, milestone change, project removal) with the user before executing.
• Close. Always include --comment with a reason. Reference the resolving PR when the issue was completed by code change.
• Milestone arguments. Use the full title from the taxonomy, never the shorthand.

Linking dependencies

Apply this section only when the user wants to record that one issue blocks or depends on another. Many workflows have no blocker relationships; skip it entirely when none apply.

GitHub exposes native issue dependencies (a "blocked by" / "blocking" relationship that renders on both issues in the UI). Prefer these over a free-text "Blocked by #N" line: native links are queryable and visible from both ends. The feature is relatively new and may be unavailable or disabled on some repositories or plans, so degrade gracefully when it is.

Key gotcha. The API identifies the blocking issue by its database id, not its issue number. Resolve the id first, then record that {issue_number} is blocked by {blocker_number}:

BLOCKER_ID=$(gh api repos/{owner}/{repo}/issues/{blocker_number} --jq '.id')
gh api --method POST \
  repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by \
  -F issue_id="$BLOCKER_ID"

The inverse "blocking" relationship appears automatically on the blocker. List or remove:

gh api repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by --jq '[.[].number]'
gh api --method DELETE repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by/$BLOCKER_ID

These endpoints need a recent REST API version. Current gh sends a recent default; if a call fails with a version error, add -H "X-GitHub-Api-Version: 2026-03-10" (or newer).

Graceful degradation. If the endpoint returns 404, 410, or 422 (feature unavailable, not enabled, or invalid target), do not block the task. Fall back to a textual "Blocked by #N" line in the issue body and tell the user the native link could not be set. Always confirm a successful link with the list call above.

Triage

When triaging a finding from code, logs, review, or conversation into the backlog:

1. Extract the concern. State it in one sentence.
2. Duplicate check. Run the procedure in "Before creating an issue" above (BLOCKING).
3. Classify. If ISSUE_TYPES is configured, pick one. Pick labels per the detected convention.
4. Place in milestone. Match the milestone whose theme fits the concern, or omit.
5. Draft the body using the template for the chosen kind of work.
6. Present the full gh issue create command for review before executing.

Quality checklist

Before executing gh issue create, verify:

• [ ] Taxonomy fetched this session (or cache is under 24h old)
• [ ] ISSUES_ENABLED: true
• [ ] Duplicate check performed
• [ ] Title: imperative, under 80 chars, no trailing period
• [ ] Issue type assigned via GraphQL updateIssue if ISSUE_TYPES is configured (else skipped)
• [ ] At least one label from taxonomy, following the detected convention
• [ ] Milestone uses full title from taxonomy, or omitted when MILESTONES: (none open) or no milestone fits
• [ ] Body matches the template for the chosen kind of work
• [ ] Verification criteria present for Bug and Feature
• [ ] No usernames, keys, internal URLs, tokens, or personal information
• [ ] No solution prescribed in bug reports
• [ ] Related issues referenced with #NNN where applicable
• [ ] --project uses project name from taxonomy, or omitted when PROJECT_BOARDS is empty
• [ ] Blocker relationships, when the workflow uses them, linked natively (or a textual "Blocked by #N" fallback added when the API is unavailable)

Error recovery

| Error | Recovery | |---|---| | ISSUES_ENABLED: false | Stop. The repository does not use GitHub Issues. | | Issue type not found | Re-run taxonomy without --cached; use exact node_id from output. | | Milestone not found | Re-run taxonomy without --cached; if still no match, omit --milestone. | | Label not found | Re-run taxonomy without --cached; label may have been renamed or deleted. | | Project not found | gh project list --owner to verify name and access. | | HTTP 403 on project | gh auth refresh -s project,read:project to add project scope. | | HTTP 422 on create | Check for duplicate title or missing required fields. | | GraphQL updateIssue returns null | Verify the type node_id matches the current org's ISSUE_TYPES output. | | HTTP 404/410/422 on dependencies/blocked_by | Native dependencies may be unavailable or not enabled for this repo; fall back to a textual "Blocked by #N" note. Confirm issue_id is the blocker's database id, not its issue number. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sergeyklay
• Source: sergeyklay/.agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.