From github-author
Encodes GitHub issue authoring conventions including present-progressive titles, outcome-focused bodies, problem-space framing, and definition-of-done patterns. Must be loaded before composing any issue title or body, whether drafting interactively or creating programmatically with gh issue create.
npx claudepluginhub notorious-ai/claude-plugins --plugin github-authorThis skill uses the workspace's default tool permissions.
Effective issues focus on the **why** over the **how**. They describe desired outcomes rather than prescribing implementation steps. The issue author specifies what needs to happen; the assignee determines how to accomplish it.
Writes articles, guides, blog posts, tutorials, and newsletters in a voice from examples or brand guidance. For polished long-form content with structure, pacing, and credibility.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Executes repo commands, inspects git state, debugs CI failures, and pushes narrow fixes with exact proof of execution and verification. Use for command runs, repo checks, or evidence-based changes.
Effective issues focus on the why over the how. They describe desired outcomes rather than prescribing implementation steps. The issue author specifies what needs to happen; the assignee determines how to accomplish it.
Issues track ongoing work. The title reflects this with present progressive verbs - work that is happening, not a command to execute.
Think: "This issue is _____ (verb+ing)"
| Imperative (avoid) | Present Progressive (prefer) |
|---|---|
| Add timezone support | Supporting user timezone preferences |
| Fix search crash | Fixing search crash on large date ranges |
| Implement caching | Improving response times for frequent queries |
| Remove deprecated API | Removing legacy v1 API endpoints |
The imperative mood suits PRs (commands that execute on merge). Present progressive suits issues (work in progress).
Issue titles use present progressive, beginning with a meaningful verb:
Format: <Verb+ing> <what is being accomplished>
Examples by type:
Supporting user timezone preferencesFixing search crash on large date rangesMigrating authentication to passport-nextInvestigating duplicate order submissionsEvaluating GraphQL migration for public APIBefore drafting an issue, gather context:
Draw from the discussion that surfaced the need:
When context is incomplete, ask proactively. The motivation behind an issue is essential for effective tracking.
Issues live in the problem-space: they define what needs solving without prescribing how. The body must surface the context that makes the problem clear and the outcome verifiable.
Issues describe what the diff cannot convey (because the diff doesn't exist yet). The body must explain:
Use intelligence to detect when essential context is missing. When gaps exist, ask targeted questions before drafting:
If the user cannot provide the information after being asked, insert actionable placeholders that specify exactly what information is missing and how to obtain it:
[FILL: Interview support team for frequency of this complaint][FILL: Check analytics for user journey drop-off data][FILL: Ask product owner for priority relative to roadmap]Placeholders must be specific enough that someone can act on them immediately.
Check for existing context:
.github/ISSUE_TEMPLATE/Use gh issue list to discover related work. Reference relevant issues to connect efforts.
Issues are problem-space documents. They define what needs solving and why it matters. PRs (solution-space) explain how; issues explain why.
The body explains why this issue exists and what outcome is needed. Leave the how to the assignee. Implementation prescription removes agency from the person doing the work and often misses better approaches.
The first paragraph immediately follows the title without a header. This opening establishes context and motivation - the "why does this matter" that pulls readers in.
Describe goals and constraints as prose. Avoid prescriptive task lists:
Avoid:
- [ ] Add database column
- [ ] Update API endpoint
- [ ] Modify frontend form
Prefer:
User profiles lack timezone information, causing scheduled notifications
to arrive at inconvenient times. Users should be able to specify their
timezone so notifications respect their local time.
The first prescribes implementation. The second describes the outcome.
Checklists suit tracking scope or acceptance criteria as outcomes:
## Acceptance Criteria
- [ ] Users can specify timezone in profile settings
- [ ] Scheduled notifications respect user timezone
- [ ] Default timezone inferred from browser when not set
These are outcomes to achieve, not steps to implement.
Include a clear outcome statement. The pattern "By the time this Issue is complete, the system will have..." works well for defining scope and completion criteria.
Examples:
This framing forces clarity about what "done" means and helps prevent scope creep.
Before creating an issue, check for templates in .github/ISSUE_TEMPLATE/. Templates encode repository-specific conventions. When a template applies to the issue type, follow its structure.
While uniform principles apply to all issues, certain types benefit from specific context. Consult references/body-structure.md for detailed guidance on:
When an issue identifies post-completion work, list it clearly at the end. See references/body-structure.md for formatting.
When creating an issue:
For detailed guidance, consult:
| File | Contains |
|---|---|
references/body-structure.md | Body format, prose flow, type specializations, linking related resources |
examples/good-issue-examples.md | Effective issue examples with probe tags showing context discovery |
examples/bad-issue-examples.md | Anti-patterns with detailed rationale for why they fail |
About probe tags: Example files use <probe> tags to demonstrate targeted questions that surface essential context. Each probe shows what to ask ("Who is affected?", "What's the impact?") and the information it reveals. Use this pattern when gathering context before drafting.
GitHub's markdown renderer treats hard newlines within a paragraph as literal line breaks. When composing --body content for gh issue create, write each paragraph as a single continuous line with no mid-sentence wraps. Newlines should only appear:
This differs from git commit -m, where hard wraps are conventional because terminals render them directly.
Before presenting the issue:
Title:
Body:
org/repo#123)