GitHub Issue Writer

Purpose

Help users draft and update well-structured GitHub issues by:

Analyzing the user's initial description
Asking targeted clarifying questions
Generating a concise title (under 72 characters)
Producing a comprehensive description using the project template
Updating existing issues on GitHub

Asking the User

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

When to Use This Skill

Use this skill when the user:

Drafting issues:

Asks to "write an issue" or "draft an issue"
Wants help structuring a bug report or feature request
Mentions wanting to document a task for GitHub
Needs to formalize a task description

For creating new issues on GitHub, use
issue-flow
when that skill is available. Otherwise use this skill to prepare the title and body, then create the issue with the available GitHub tooling.

Updating issues:

Asks to "update issue", "edit issue", or "modify issue"
Wants to "change the title" or "update description"
References a specific issue: "update issue #123", "edit https://github.com/..."
Says "update the issue" (use recently created issue from same session)

Bundled Scripts

This skill includes helper bash scripts in the

scripts/

directory:

get-issue.sh - Fetches existing issue data (title, body, labels, state)
update-issue.sh - Updates an existing issue

To use bundled scripts, execute them from the skill directory:

bash

bash scripts/get-issue.sh 123
bash scripts/update-issue.sh --issue 123 --title "New Title" --add-label "bug"

Workflow

Follow these steps in order. Adapt based on the scope and complexity of the issue.

Step 1: Gather Initial Input

Ask the user to describe what they want the issue to cover. If they've already provided a description, proceed to analysis.

Step 1.5: Determine Format

Check if the user's request indicates a preferred format:

Auto-detect Short format if keywords present:

"short issue", "minimal issue", "quick issue"

Auto-detect Default format if keywords present:

"simple issue", "draft issue", "basic issue"

If not auto-detected, ask the user which format they want, per Asking the User:

question: "What level of detail should this issue have?"
header: "Format"
options:
  - label: "Default (Recommended)"
    description: "Simple format with description, rationale, references, and implementation notes"
  - label: "Short"
    description: "Minimal format with just description and rationale (no section headers)"
  - label: "Full"
    description: "Comprehensive format with acceptance criteria, testing steps, and detailed implementation plan"

Step 2: Analyze and Categorize

Determine the issue type based on the description:

Feature: New functionality or enhancement
Bug: Something is broken or not working as expected
Task: General work item, refactoring, documentation
Question: Needs discussion or clarification

Type-to-Label Mapping:

Based on the issue type, determine the recommended label:

Type	Recommended Label	Notes
Bug	`bug`	Add `critical` if severe/blocking
Feature	`feature`	New functionality
Task	Context-based	See keywords below
Question	None	Usually doesn't need a label

Task Label Keywords:

Keywords: refactor, cleanup, reorganize, restructure →
```
refactoring
```
Keywords: improve, enhance, update, optimize, better →
```
improvement
```
Keywords: research, investigate, explore, spike, prototype →
```
r&d
```
Default (no keywords matched):
```
improvement
```

Identify which template sections are relevant based on scope:

Scope	Required Sections
Short (minimal, quick)	Brief Description, Rationale (no section headers, bold markers only)
Default (simple task, draft)	Description, Rationale; optionally References, Implementation Notes
Small (bug fix, typo)	Brief Description, Acceptance Criteria
Medium (feature, enhancement)	Brief Description, Rationale, Implementation, Acceptance Criteria
Large / Full (architecture, major feature)	All sections as needed

Format Auto-Detection:

If keywords like "short issue", "minimal issue", or "quick issue" are present, use Short format
If keywords like "simple issue", "draft issue", or "basic issue" are present, use Default format

Step 3: Interactive Questionnaire

Ask clarifying questions to fill in gaps, per Asking the User. Tailor them to the issue type and scope.

For Features:

What problem does this solve?
Are there any design references or examples?
What are the key acceptance criteria?
Any technical constraints to consider?

For Bugs:

What is the expected behavior?
What is the actual behavior?
Steps to reproduce?
Any error messages or screenshots?

For Tasks:

Why is this work needed now?
Are there dependencies on other work?
What does "done" look like?

Keep questions focused and avoid asking about things already clear from the description.

Step 3.5: Confirm Label

Based on the type-to-label mapping from Step 2, confirm the label, per Asking the User:

question: "Which label best describes this issue?"
header: "Label"
options:
  - label: "{{RECOMMENDED_LABEL}} (Recommended)"
    description: "Based on issue type: {{TYPE}}"
  - label: "{{ALTERNATIVE_LABEL_1}}"
    description: "{{DESCRIPTION_1}}"
  - label: "{{ALTERNATIVE_LABEL_2}}"
    description: "{{DESCRIPTION_2}}"
  - label: "No label"
    description: "Skip label assignment"

Example for Bug type:

options:
  - label: "bug (Recommended)"
    description: "This appears to be a bug based on the error behavior described"
  - label: "critical"
    description: "High priority bug, needs immediate attention"
  - label: "improvement"
    description: "If this is more of an enhancement than a bug"
  - label: "No label"
    description: "Skip label assignment"

Example for Feature type:

options:
  - label: "feature (Recommended)"
    description: "New functionality being added"
  - label: "improvement"
    description: "Enhancement to existing functionality"
  - label: "epic"
    description: "Large feature spanning multiple issues"
  - label: "No label"
    description: "Skip label assignment"

Example for Task type (with refactoring keywords):

options:
  - label: "refactoring (Recommended)"
    description: "Code restructuring based on keywords: refactor, cleanup"
  - label: "improvement"
    description: "General enhancement"
  - label: "r&d"
    description: "Research and exploration work"
  - label: "No label"
    description: "Skip label assignment"

Step 4: Generate Title

Create a title that:

Is under 72 characters (hard limit)
Starts with the component/area if applicable (e.g., "Button: Add loading state")
Uses imperative mood ("Add", "Fix", "Update", not "Adding", "Fixed")
Is specific but concise
Avoids redundant words like "Issue:" or "Task:"

Good examples:

Button: Add disabled state visual feedback

Fix tooltip positioning on viewport edge

```
TreeView: Implement keyboard navigation
```

Bad examples:

```
Issue: There's a problem with buttons
```
(vague, has "Issue:")

Adding a new feature for users to be able to see loading spinners

(too long, wrong mood)

Step 5: Generate Description

Use the appropriate template based on the selected format.

Writing rules (all formats):

Never start the description with a markdown header — always lead with plain text
Use present tense for existing problems ("the button does not respond", not "the button did not respond" or "added responsive button handling") — describe the issue as it currently exists
Preserve the user's original wording where possible — restructure, don't rewrite

The templates live in

references/templates.md

, one per format — Full, Default, and Short. Read the one matching the chosen format.

## Template Section Guidelines

below says what belongs in each section.

Step 6: Present to User

Show the user:

Title: The generated title
Description: The formatted description
Type suggestion: bug, feature, enhancement, documentation, etc.
Label suggestions: Based on the content

Ask if they want any modifications. Use a structured question tool when available; otherwise ask directly in chat.

Update Workflow

Use this workflow when the user wants to update an existing issue.

Step 1: Identify the Issue

Determine which issue to update:

Issue specified: User provides issue number or URL
- ```
#123
```
  ,
```
123
```
  ,
```
https://github.com/owner/repo/issues/123
```
Recent issue in session: If an issue was just created in this conversation, offer to use that
Ask: If neither, ask the user for the issue number or URL

Step 2: Fetch Current Issue Data

bash

bash scripts/get-issue.sh <issue-number-or-url>

Show the user:

Current title
Current description (summarized if long)
Current labels

Step 3: Determine Changes

Ask the user what they want to change:

Title only
Description only
Both title and description
Labels (add or remove)

Step 4: Apply Changes

For description updates:

If minor edit: Apply the specific change
If rewrite: Use the same template logic as creating (Steps 2-5 of create workflow)

For title updates:

Follow the same title guidelines (under 72 chars, imperative mood)

Step 5: Present Changes for Approval

Important: Always show the changes to the user before updating the issue on GitHub. Skip this step only if the user explicitly requests to update without preview (e.g., "update without showing", "skip preview").

Show the user:

Before: Current title/description
After: New title/description
Label changes: Labels being added/removed

Ask for confirmation before updating. Use a structured question tool when available; otherwise ask directly in chat.

Step 6: Update on GitHub

bash

bash scripts/update-issue.sh \
  --issue {{ISSUE_NUMBER}} \
  --title "{{NEW_TITLE}}" \
  --body "{{NEW_DESCRIPTION}}" \
  --add-label "{{LABEL}}" \
  --remove-label "{{LABEL}}"

Return the updated issue URL to the user.

Template Section Guidelines

Description (Required)

The opening paragraph before any sections. Length varies by format: Short 4-6 sentences, Default 4-8 sentences, Full 1-2 sentences (detailed sections follow). Describe the issue in present tense. Preserve the user's original phrasing — restructure for clarity, don't rewrite.

Rationale (Optional)

Explain the "why" when it's not obvious:

Business/technical value
Why this approach vs alternatives
Architectural decisions

References (Optional)

Links that provide context:

Design files (Figma, screenshots)
Similar implementations
Documentation or RFCs
Related issues/PRs

Things to Consider (Optional)

Important aspects affecting implementation:

Edge cases
Performance considerations
Integration points
Future extensibility

Implementation (Medium/Large scope)

Functional checklist, not micromanagement:

Clear about WHAT needs to be done
Context for WHY
Code snippets for complex patterns
Logical order

UI Behavior (If applicable)

Expected user interactions:

Focus management
Keyboard navigation
Animations/transitions
Responsive behavior

Acceptance Criteria (Required)

Testable yes/no checkboxes defining completion.

Testing Steps (Optional)

How to find and test in the application:

Navigation steps
Actions to trigger
Expected outcomes

Examples (Optional)

Screenshots, mockups, or code examples showing expected result.

Out of Scope (Optional)

What is explicitly NOT part of this task. Prevents scope creep.

Technical Constraints (Optional)

Specific requirements:

Performance targets
Browser support
Accessibility standards

Prerequisites

```
gh
```
CLI installed and authenticated (
```
gh auth login
```
) — required for updating issues
Must be run from within a GitHub repository for update operations

See

references/helper-scripts.md

for detailed script documentation, usage examples, and exit codes.

Error Handling

If
```
gh
```
CLI is not available, skip update operations and just provide the formatted output
If not in a git repository, skip GitHub integration and just provide the formatted output

issue-writer

NPX Install

Tags

SKILL.md Content

GitHub Issue Writer

Purpose

Asking the User

When to Use This Skill

Bundled Scripts

Workflow

Step 1: Gather Initial Input

Step 1.5: Determine Format

Step 2: Analyze and Categorize

Step 3: Interactive Questionnaire

Step 3.5: Confirm Label

Step 4: Generate Title

Step 5: Generate Description

Step 6: Present to User

Update Workflow

Step 1: Identify the Issue

Step 2: Fetch Current Issue Data

Step 3: Determine Changes

Step 4: Apply Changes

Step 5: Present Changes for Approval

Step 6: Update on GitHub

Template Section Guidelines

Description (Required)

Rationale (Optional)

References (Optional)

Things to Consider (Optional)

Implementation (Medium/Large scope)

UI Behavior (If applicable)

Acceptance Criteria (Required)

Testing Steps (Optional)

Examples (Optional)

Out of Scope (Optional)

Technical Constraints (Optional)

Prerequisites

Error Handling