gh-issues
Installation
SKILL.md
Writing GitHub issues
An issue is a small contract: it says what's wrong or wanted, and how everyone will know it's done. Written well, it's the spec someone (often an agent) implements against without needing the backstory. Written badly, it's noise that someone else has to decode, deduplicate, or reopen. This standard is how to write the good kind. Apply it to every issue you touch — it's not a step you wait to be asked for.
Before you file
- Every change gets an issue. Every PR links one, however small the change — a two-class CSS fix included. File it before or alongside the PR, not afterwards. It's for traceability: the issue is where the reason for a change lives. (The
gh-prsskill links it withCloses #N.) - Search first. Look for an existing open or recently-closed issue for the same thing. If one exists, add to it (a comment, a reproduction, a +1 with new detail) instead of opening a duplicate. Link related issues rather than restating them.
- One issue, one concern. A bug and a feature it inspired are two issues. If you catch yourself writing "and also" about a different area, split it. Tangled issues never fully close.
- Group related items, but keep it small. Several changes to the same page, section, or component, of the same kind (
feat,fix,ci…), are one concern: one issue with a short theme title and oneDone whenline per item. Keep it to about 3–6 items; past that, split by area. Different areas or kinds get their own issues. An issue is a spec, not a bible. - File only what's actionable. An issue is a discrete unit of work with a definition of done — not a vague "improve X" or a place to think out loud. If it isn't yet actionable, say what's unknown and what would make it so.
- Use the repo's template. If
.github/ISSUE_TEMPLATE/exists, follow the matching template (bug / feature / chore) and fill every heading; writen/arather than deleting a heading you can't fill. (Thegh-templatesskill sets these up.)
Title
- Prefix with the Conventional-Commit type the work will carry:
fix:,feat:,chore:(ordocs:/refactor:/test:/ci:/build:when one fits). This sets the type from the first word and lines the issue up with its eventual commit and PR. (See theconventional-commitsskill.) - Say the specific thing, imperatively.
fix: crash when saving an empty profile— notbug,broken, orsaving issue. A title should be enough to tell two issues apart in a list.