| name | issue-tracker |
| description | File, update, and close GitHub work as one epic with native sub-issues. Dedup open and closed issues first. Edit status only inside marker sections. Refresh the epic checklist so it matches its children. Triggers: issue tracker, file an issue, track this issue, open an epic, update the epic, close the issue, refresh the epic checklist, attach a sub-issue. |
| argument-hint | [issue action - file | update | close | refresh-epic | full handoff] |
Issue tracker
User wants an issue action done. Here is how those actions work.
dedup -> do the work -> markers only -> numbers + URLs
Run every step the ask needs in one go (file, label, attach, refresh, and so on). The issue-tracker agent is the primary handler for one action per turn; this skill is the session path when the agent is unavailable or the ask spans several steps.
Prefer the same warm issue-tracker agent for follow-ups on the same issue or a related issue on the same epic. Spawn a new agent only for an unrelated work-stream or when the warm agent is gone.
Voice
Use the plain-brief output style (output-styles/plain-brief.md). End with the issue number(s) and URL(s) the caller must keep.
Gotchas
Append a bullet when an action fails in a new way.
- Use REST
.id, not display #N, to attach a sub-issue - operation-matrix.
gh attach: -F sub_issue_id=<n> (typed int), never -f.- Status goes in markers, not comments - comments are cross-links only.
- Dedup open and closed; closed twin -> reopen vs file new, never silent refile.
- Edit only between markers - free-form epic edits break the children checklist.
- Auto-close is PR-body-first: a related-only UI link does not close the issue on merge.
The model
One epic issue owns a work-stream. Each unit of work is a native GitHub sub-issue under it. The epic checklist and every status block live inside marker pairs. Skeletons and refresh steps: reference/epic-and-sub-issue-model.md.
Labels
- Parent:
epic.
- Sub-issue:
type: roadblock, type: task, type: bug, or type: enhancement.
Create a missing label, then apply it. Label create is in the operation matrix.
Markers
- Status (any issue):
<!-- issue-tracker:status --> … <!-- /issue-tracker:status -->
- Children checklist (epic only):
<!-- issue-tracker:children --> … <!-- /issue-tracker:children -->
Update path: read body -> replace only the text between the target pair -> write the full body back.
Dedup
Search open and closed issues on the target repo before create. Open twin -> update in place. Closed twin -> ask reopen vs file new.
Tools
Prefer GitHub MCP. Fall back to gh on the same REST endpoints. Full map and .id rule: reference/operation-matrix.md.
Handoff input
Optional issue-candidate JSON from orchestrator or closeout. Full schema and consume path: reference/handoff-schema.md.
Close the sub-issue through the PR (required when a fix ships)
GitHub closes the sub-issue when someone merges a pull request into the default branch and that PR carries a closing keyword for the issue.
Required on the PR that merges into the default branch: put Closes #N in the PR body for each finished sub-issue. One keyword per issue: write Closes #12 and Closes #13, not Closes #12, #13 (only the first number closes in the comma form).
Preferred on commits: also put Closes #N in the first commit message when the fix starts. Commit alone is backup; the PR body is the contract.
Stacked / intermediate PRs that do not merge into the default branch: use a plain #N reference in the body so the issue links without a false close promise. Put Closes #N only on the PR that actually lands on the default branch.
Not enough: a Development "related" link with no closing keyword. Not enough: closing the PR without merging.
Who owns #N: the agent or session writing the PR must use the correct sub-issue number. Nothing in this package verifies the number matches the fix.
Return shape
Reply with every affected issue number and URL - no narration after that payload.
File index
| File | Purpose |
|---|
SKILL.md | Hub: how issue actions work, gotchas, model, markers, dedup, PR auto-close, return shape |
reference/operation-matrix.md | MCP + gh per action; sub-issue .id rule |
reference/epic-and-sub-issue-model.md | Epic model, markers, body skeleton, checklist refresh |
reference/handoff-schema.md | Issue-candidate JSON and consume flow |
