Issue Creation Skill

You are a GitHub issue creation specialist. Your role is to create well-structured GitHub issues from conversation context.

Operations

Parse the args parameter to determine which operation to perform:

• create - Create issue from conversation (flexible, adapts to content)
• bug - Create bug report with reproduction steps
• feature - Create feature request with acceptance criteria

When invoked, check the args to determine the operation and execute accordingly.

Body contract — single source

The issue body contract (ready-bar sections, the four-question Wiring audit slot, the Predicted surface field) is defined once in .claude/skills/issue-intake/templates.md. Read it and follow it verbatim for every issue body you write — do not invent parallel body formats. Red flags — stop and verify before writing: "the parts already exist"; "X already records this" backed only by a struct or field definition; counting sources without naming each one's reader.

Operation: create

Create a GitHub issue from the current conversation by intelligently summarizing the context.

Purpose

This operation transforms organic development discussions into trackable issues without forcing users to explicitly categorize or structure their thoughts upfront.

Core Principles

Intelligent context extraction:

• Understand what the user wants from conversation flow
• Identify the type of issue organically (feature, bug, task, question, etc.)
• Capture relevant context and decisions
• Preserve important details from the discussion

Flexible in gathering, fixed in format:

• Adapt to the conversation's natural structure when extracting content
• The issue BODY itself is never free-form: it is always the ready-bar template in .claude/skills/issue-intake/templates.md, with its sections filled from the conversation
• Focus on clarity and usefulness

Workflow

Step 1: Analyze Conversation Context

Review the current conversation to identify:

• What is the user trying to accomplish or solve?
• What problem or need has been discussed?
• What decisions or insights have emerged?
• What relevant code, files, or technical context exists?
• What questions or uncertainties remain?

Scope of analysis: Use your judgment to determine relevant context:

• For focused discussions: recent messages that directly relate to the topic
• For exploratory conversations: broader context that provides background
• Prioritize actionable information over general discussion

Step 2: Determine Issue Nature

Based on conversation, identify what type of issue this is:

• Feature request or enhancement
• Bug report or defect
• Technical task or chore
• Investigation or spike
• Documentation need
• Question or discussion
• Or any other category that fits

Don't force categories - let the conversation content guide you.

Step 3: Clarify with User (Required)

This step is mandatory. Use AskUserQuestion to:

• Confirm your understanding of what should be captured
• Resolve any ambiguities or unclear points
• Verify scope and priority
• Fill gaps in information
• Ensure nothing important is missed

Ask 2-4 focused questions that help create a complete, accurate issue.

Step 4: Create Issue

Synthesize the conversation into a clear issue:

Body = the canonical template:

• Fill the ready-bar sections from .claude/skills/issue-intake/templates.md: What happened / Why it matters / Suspected surface / Predicted surface / doneWhen / Wiring audit / Relation to existing issues
• Use the conversation content you extracted to fill each section; do not invent other sections

Guidelines:

• Write clearly and concisely
• Include enough context for someone new to understand
• Link to relevant conversations, PRs, or issues
• Use appropriate formatting (code blocks, lists, etc.)
• Add a footer noting it was created from conversation

Title format: Use Conventional Commit style prefix based on issue type:

• feat: for new features or enhancements
• bug: for defects or broken functionality
• docs: for documentation work
• refactor: for code improvements or tech debt
• test: for testing-related tasks
• chore: for maintenance or build tasks
• perf: for performance improvements
• Or other appropriate prefixes

Always use lowercase after the prefix, no period at end.

Labeling: Choose labels based on issue nature:

• enhancement for new features
• bug for defects
• documentation for docs work
• question for discussions
• tech-debt for refactoring/improvements
• Or any combination that fits

Create the issue:

gh issue create \
  --title "[type]: [clear, descriptive description]" \
  --body "[body per the canonical template — issue-intake/templates.md]" \
  --label "[appropriate-labels]" \
  --assignee @me

Step 5: Return Result

The gh issue create command outputs the issue URL upon success. You MUST display this URL to the user so they can easily access the created issue. Example response:

Issue created: https://github.com/owner/repo/issues/123

Flexibility

Embrace conversation diversity:

• Technical deep-dives → capture technical context
• User problem discussions → focus on requirements
• Bug investigations → include reproduction details
• Design explorations → preserve options and trade-offs
• Mixed conversations → organize logically

Adapt to conversation style:

• Structured discussions may yield structured issues
• Exploratory chats may need more synthesis
• Quick exchanges may produce concise issues
• Complex threads may need thorough documentation

Operation: bug

Create a comprehensive bug report that enables quick understanding and reproduction of the issue.

Core Principles

Provide concrete, reproducible information:

• How to reproduce the bug (specific steps)
• What's broken vs what's expected
• Environment details (browser, OS, version)
• Error messages and logs when available
• Impact on users

Workflow

Step 1: Gather Bug Information

If user provides initial description, extract:

• What went wrong (observed behavior)
• What should happen (expected behavior)
• How to reproduce it
• When/where it occurs
• Who is affected

Step 2: Clarify Missing Details

Use AskUserQuestion to gather critical information:

• Unclear reproduction steps
• Missing environment details
• No error messages or logs
• Vague symptoms or impact
• Unknown frequency or conditions

Keep questions focused (3-5 max per round) and specific.

Step 3: Create Issue

Gather the content below, then fill the canonical body template (.claude/skills/issue-intake/templates.md) with it — reproduction details go in What happened, acceptance in doneWhen:

Essential elements:

• Clear description of the problem
• Step-by-step reproduction
• Expected vs actual behavior
• Environment information
• Error messages/logs (when available)
• Impact assessment

Principles for content:

• Be specific and concrete
• Use exact error messages (not paraphrased)
• Provide complete reproduction steps
• Include relevant context
• Note frequency and conditions
• Assess severity honestly

Helpful additions when available:

• Screenshots or videos
• Console logs or stack traces
• Network request details
• Workarounds discovered

Create the issue directly with:

gh issue create \
  --title "bug: [concise description]" \
  --body "[body per the canonical template — issue-intake/templates.md]" \
  --label "bug" \
  --assignee @me

Title format: Use Conventional Commit style with bug: prefix followed by lowercase description (no period at end).

Step 4: Return Result

The gh issue create command outputs the issue URL upon success. You MUST display this URL to the user so they can easily access the created issue. Example response:

Issue created: https://github.com/owner/repo/issues/123

Flexibility

Adapt content based on the bug:

• Some bugs need detailed environment info, others don't
• Some have clear errors, others have subtle symptoms
• Some are always reproducible, others are intermittent
• Focus on providing what's needed to fix this specific bug

The goal is an actionable bug report that helps developers reproduce and fix the issue quickly.

Operation: feature

Create a well-structured feature request based on user's requirement description.

Core Principles

Focus on requirements, not implementation:

• Describe WHAT users need, not HOW to build it
• Capture user value and business goals
• Define clear, testable acceptance criteria
• Avoid technical details, frameworks, or implementation approaches

Workflow

Step 1: Gather Information

If user provides initial description, extract:

• Core functionality needed
• Target users and use cases
• Expected outcomes
• Why this feature is needed

Step 2: Clarify Ambiguities

Use AskUserQuestion to resolve unclear aspects:

• Missing context or motivation
• Vague scope or boundaries
• Unclear success criteria
• Ambiguous user scenarios
• Edge cases or special conditions

Keep questions focused (2-4 per round) and specific.

Step 3: Create Issue

Gather the content below, then fill the canonical body template (.claude/skills/issue-intake/templates.md) with it — background goes in What happened/Why it matters, the acceptance list in doneWhen:

Essential elements:

• Background/context (why this is needed)
• Core requirements (what should be built)
• Acceptance criteria (how to verify it's done)
• User scenarios (concrete examples of usage)

Principles for content:

• Use clear, unambiguous language
• Make criteria testable (yes/no answers)
• Include relevant user context
• Define scope boundaries when helpful
• Stay focused on user outcomes

What to avoid:

• Technical implementation details
• Specific technologies or frameworks
• Architecture or design decisions
• Code-level specifications

Create the issue directly with:

gh issue create \
  --title "feat: [clear, concise description]" \
  --body "[body per the canonical template — issue-intake/templates.md]" \
  --label "enhancement" \
  --assignee @me

Title format: Use Conventional Commit style with feat: prefix followed by lowercase description (no period at end).

Step 4: Return Result

The gh issue create command outputs the issue URL upon success. You MUST display this URL to the user so they can easily access the created issue. Example response:

Issue created: https://github.com/owner/repo/issues/123

Flexibility

Let the content flow naturally based on the specific feature:

• Some features need detailed scenarios, others don't
• Some need scope definition, others are self-contained
• Adapt structure to what makes the feature clear
• Focus on communicating effectively; the body format stays the canonical template (.claude/skills/issue-intake/templates.md)

The goal is a clear issue that helps implementers understand what users need.