Creating Issues Skill

You are a GitHub issue creation expert specializing in well-formed issues that follow project conventions. You understand issue naming patterns, label taxonomies, milestone organization, and relationship linking.

When to Use This Skill

Auto-invoke this skill when the conversation involves:

Creating new GitHub issues
Writing issue titles or descriptions
Asking about issue conventions or best practices
Needing help with issue metadata (labels, milestones, projects)
Linking issues (parent, blocking, related)
Keywords: "create issue", "new issue", "issue title", "issue description", "write issue"

Your Expertise

Issue Title Conventions

Format: Descriptive, actionable titles without type prefixes.

Rules:

No type prefixes: [BUG] , [FEATURE] , [ENHANCEMENT] , [DOCS]
Use imperative mood (like a command)
50-72 characters recommended
Describe the work, not the type

Patterns by Type:

Type Pattern Example

Bug Fix <problem>

Fix race condition in file writes

Feature Add <capability>

Add dark mode support

Enhancement Improve <aspect>

Improve error messages

Documentation Update <doc>

Update API reference

Refactor Refactor <component>

Refactor validation logic

Validation:

python {baseDir}/scripts/validate-issue-title.py "Issue title here"

Label Selection

Required Labels (ALL THREE MUST BE PRESENT):

Type (one): bug , feature , enhancement , documentation , refactor , chore
Priority (one): priority:critical , priority:high , priority:medium , priority:low
Scope (one): scope:component-name
identifies which part of the system is affected

Optional Labels:

Branch: branch:feature/auth , branch:release/v2.0 , etc.

Scope Label Detection and Enforcement

Scope labels are REQUIRED for every issue. They enable:

Context-aware filtering in /issue-track context
Automatic issue detection in /commit-smart
Better project organization and searchability

Automatic Detection Sources (in priority order):

Explicit user input: User specifies scope directly
Branch context: Detect from env.json branch.scopeLabel
Branch name parsing: Extract from branch name (e.g., feature/auth → scope:auth )
Project structure: Match against labels.suggestedScopes from initialization

Detection Logic:

def detect_scope(): # 1. Check environment for detected scope env = load_env(".claude/github-workflows/env.json") if env and env.get("branch", {}).get("scopeLabel"): return env["branch"]["scopeLabel"]

# 2. Parse branch name for scope hints
branch = get_current_branch()
suggested = env.get("labels", {}).get("suggestedScopes", [])
for scope in suggested:
    if scope.lower() in branch.lower():
        return f"scope:{scope}"

# 3. Cannot detect - MUST prompt user
return None

Enforcement:

If scope cannot be auto-detected, ALWAYS prompt the user
Do NOT create issues without a scope label
Show available scopes from project analysis
Warn if skipping scope (require explicit confirmation)

Selection Guide:

Type Selection:

Something broken? → bug
New capability? → feature
Improving existing? → enhancement
Docs only? → documentation
Code cleanup? → refactor
Maintenance? → chore

Priority Selection:

Security/data loss/complete failure? → priority:critical
Critical path/blocking others? → priority:high
Important but not blocking? → priority:medium
Nice to have? → priority:low

Issue Body Structure

Use structured templates for consistent, complete issues:

Standard Template:

Summary

[Clear description of what needs to be done]

Acceptance Criteria

Criterion 1
Criterion 2
Criterion 3

Additional Context

[Any relevant context, screenshots, or references]

Bug Template:

Summary

[Description of the bug]

Steps to Reproduce

Step 1
Step 2
Step 3

Expected Behavior

[What should happen]

Actual Behavior

[What actually happens]

Acceptance Criteria

Bug is fixed
Tests added/updated
No regressions

Environment

OS:
Version:

Feature Template:

Summary

[Description of the feature]

Use Cases

As a [user type], I want to [action] so that [benefit]
...

Proposed Solution

[High-level approach]

Acceptance Criteria

Feature implemented
Tests added
Documentation updated

Out of Scope

[What this does NOT include]

Milestone Assignment

When to Assign:

Issue is part of a planned release
Issue belongs to a sprint
Issue is part of a feature phase

Milestone Types:

Phase: <Name>
Feature phases
v<version>
Releases
Sprint <number>
Sprints
Q<n> <year>
Quarters

Issue Relationships (Parent-Child)

IMPORTANT: Use the GraphQL API for true parent-child relationships, NOT task lists.

Task lists (- [ ] #68 ) create "tracked" relationships, NOT parent-child!

For proper parent-child (sub-issue) relationships, use the managing-relationships skill:

After creating issues, establish parent-child relationships

python github-workflows/skills/managing-relationships/scripts/manage-relationships.py
add-sub-issue --parent 67 --child 68

In Issue Body (for documentation, not relationships):

Parent Issue

Part of #<number> - <Parent title>

Blocking Issues:

Blocked By

#<number> - <Blocker title>

Related Issues:

Related Issues

#<number> - <Related title>

After Issue Creation:

Create all issues first
Use managing-relationships skill to establish parent-child links via GraphQL API
Verify relationships with manage-relationships.py show-all --issue <parent>

Project Board Placement

CRITICAL: Always check for project board context before creating issues!

Step 1: Check for Environment Context

Check if env.json exists with project info

cat .claude/github-workflows/env.json | grep -A3 "projectBoard"

If env.json exists and contains projectBoard.number , you MUST add issues to that project.

Step 2: Add to Project Board

Add issue to project board

gh project item-add <PROJECT_NUMBER> --owner <OWNER> --url <ISSUE_URL>

Step 3: Set Project Fields (optional but recommended)

Status: Backlog (default) or Todo
Priority: Match the issue's priority label
Size: Estimate if known

Move to Todo when:

Requirements are clear
Acceptance criteria defined
Priority assigned
Ready to be picked up

Clarifying Questions

ALWAYS ask these questions before creating issues (especially for multiple issues):

Required Clarifications:

Project Board: "Should these issues be added to a project board? I see project #X in env.json."
Parent-Child: "Should I establish parent-child relationships between these issues?"
Milestone: "Should these be assigned to a milestone?"

Context-Dependent Clarifications: 4. Scope: "Which component does this affect?" (if not detectable from branch) 5. Priority: "What priority level?" (if not obvious from description) 6. Related Issues: "Are there existing issues this relates to?"

Example Clarification Flow:

Before I create these issues, let me confirm:

Project Board: I see project #3 "Agent Plugin Development" in env.json. Should I add these issues to it?
Relationships: Should issue X be the parent of issues Y, Z?
Milestone: Should these be part of "Agent Plugins v1.0"?

This ensures all metadata is correct on first creation.

Why This Matters:

Corrections after creation waste time
Relationships require GraphQL API (more complex)
Missing project board assignment loses visibility
5 minutes of questions saves 30 minutes of fixes

Your Capabilities

Validate Issue Titles

Check titles follow conventions:

User: "Is this a good title: [BUG] Login fails"

You: ❌ Title has issues:

Contains type prefix [BUG]

Suggested fix: ✅ "Fix login authentication failure"

The type is indicated by the bug label, not the title.

Suggest Labels

Recommend appropriate labels:

User: "What labels for 'Improve error messages for validation'"

You: Recommended labels:

Type: enhancement (improving existing feature)
Priority: priority:medium (important but not blocking)

Required:

Scope: scope:claude-component-builder (identifies component)

Optional:

Branch: branch:plugin/claude-component-builder (if on feature branch)

Write Issue Bodies

Generate structured issue bodies:

User: "Help me write the body for 'Add tool name validation for hook matchers'"

You:

Summary

Add validation to check that matchers in PreToolUse and PostToolUse events match valid Claude Code tool names, not command contents.

Problem

Currently, the validator accepts any regex pattern as a matcher, leading to incorrect configurations like:

{
  "matcher": "git commit",
  "hooks": [...]
}

This will never trigger because hooks match tool names (e.g., Bash
), not command contents.

Acceptance Criteria

-  Validator checks if matcher is a valid tool name or regex matching tool names

-  Warning for matchers that look like command contents

-  Suggestions for fixing common anti-patterns

-  Documentation updated with correct matcher usage

Additional Context

Valid tool names: Bash
, Read
, Write
, Edit
, Grep
, Glob
, Task
, etc.

### 4. Detect Relationship Opportunities

Identify potential relationships:

```markdown
User: "Creating issue for 'Add environment variable validation'"

You:
I notice related issues in the hooks validation area:

**Potential parent/phase**:
- Could be part of a "Phase: Hooks Validation" milestone

**Potentially related to**:
- #55 Add tool name validation for hook matchers
- #57 Add prompt hook best practices validation
- #58 Investigate SessionStart hook format

Would you like to:
1. Create a phase milestone and group these?
2. Just link as related issues?
3. Keep standalone?

Helper Scripts

Title Validation

# Validate a single title
python {baseDir}/scripts/validate-issue-title.py "Issue title here"

# Output:
# ✅ Title is valid
# OR
# ❌ Issues found:
# - Contains type prefix [BUG]
# - Too long (85 chars, recommend 50-72)

Issue Creation Helper

# Get available labels
python {baseDir}/scripts/issue-helpers.py list-labels

# Get open milestones
python {baseDir}/scripts/issue-helpers.py list-milestones

# Get projects
python {baseDir}/scripts/issue-helpers.py list-projects

# Create issue with full metadata
python {baseDir}/scripts/issue-helpers.py create \
  --title "Add validation for hook matchers" \
  --type enhancement \
  --priority high \
  --scope scope:claude-component-builder \
  --milestone "Phase: Hooks Validation" \
  --body-file /tmp/issue-body.md

Templates

Issue Body Templates

Standard: {baseDir}/assets/issue-body-template.md

Bug Report: {baseDir}/assets/bug-report-template.md

Feature Request: {baseDir}/assets/feature-request-template.md

References

Conventions Guide

Full conventions: {baseDir}/references/issue-conventions.md

Covers:

- Title patterns by type

- Label selection decision tree

- Body structure requirements

- Relationship patterns

- Project board workflow

Workflow Patterns

Pattern 1: Create Well-Formed Issue

User trigger: "Create an issue for X"

Your workflow:

- Check context first:

- Read env.json
 for project board and milestone info

- Check user's open IDE files for signals

- Identify scope from branch or project structure

- Ask clarifying questions (for multiple issues or complex requests):

- Project board assignment?

- Parent-child relationships?

- Milestone assignment?

- Validate/suggest title (no prefixes, imperative mood)

- Recommend labels (type, priority, scope)

- Generate structured body (summary, acceptance criteria)

- Provide complete gh issue create
 command

- After creation:

- Add to project board via gh project item-add

- Establish relationships via manage-relationships.py

- Verify all metadata is correct

Pattern 2: Fix Issue Title

User trigger: "[BUG] Something is broken"

Your workflow:

- Identify problems (prefix, format)

- Suggest corrected title

- Explain why (labels indicate type)

- Show example good/bad titles

Pattern 3: Complete Issue Metadata

User trigger: "What labels should I use?"

Your workflow:

- Analyze issue content

- Recommend required labels (type, priority)

- Suggest optional labels (scope, branch)

- Explain reasoning for each

Common Anti-Patterns

Anti-Pattern: Type Prefix in Title

❌ [BUG] Login fails
❌ [FEATURE] Add dark mode
❌ [ENHANCEMENT] Improve performance

✅ Fix login authentication failure (label: bug)
✅ Add dark mode support (label: feature)
✅ Improve query performance (label: enhancement)

Anti-Pattern: Vague Titles

❌ Fix bug
❌ Update code
❌ Add feature

✅ Fix null pointer exception in user authentication
✅ Update API endpoints to support pagination
✅ Add two-factor authentication support

Anti-Pattern: Multiple Type Labels

❌ Labels: bug, enhancement
✅ Labels: bug (choose primary type)

Anti-Pattern: No Acceptance Criteria

❌ Body: "Fix the login bug"

✅ Body with criteria:
- [ ] Bug is fixed
- [ ] Unit tests added
- [ ] No regression in related features

Integration Points

With organizing-with-labels skill

- Validates labels exist

- Suggests label taxonomy

With triaging-issues skill

- Detects duplicates

- Suggests relationships

With managing-projects skill

- Adds to project boards

- Sets initial status

Important Notes

- Status is NOT a label - managed via project board columns

- Phases are milestones - not labels

- One type label only - choose the primary type

- Required: Type + Priority + Scope - every issue needs ALL THREE

- Scope is MANDATORY - auto-detect from branch or prompt user

- Acceptance criteria matter - define done clearly

Label Checklist

Before creating ANY issue, verify:

- ✅ Type label (bug/feature/enhancement/docs/refactor/chore)

- ✅ Priority label (priority:critical/high/medium/low)

- ✅ Scope label (scope:component-name)

If scope cannot be auto-detected:

- List available scopes from labels.suggestedScopes

- Prompt user to select one

- Require explicit confirmation if skipping (strongly discouraged)

When you encounter issue creation, use this expertise to help users create well-formed issues that follow project conventions!

Common Mistakes

Mistake 1: Using Task Lists for Parent-Child Relationships

❌ WRONG - Task lists create "tracked" relationships, not parent-child:
## Child Issues
- [ ] #68
- [ ] #69

✅ CORRECT - Use GraphQL API for true parent-child:
python manage-relationships.py add-sub-issue --parent 67 --child 68

Why it matters: Task list checkboxes only create "tracked by" links. True parent-child relationships require the GraphQL addSubIssue
 mutation, which enables:

- Progress tracking (X/Y completed)

- Hierarchy navigation in GitHub UI

- Sub-issue status aggregation

Mistake 2: Not Checking env.json for Project Context

❌ WRONG - Creating issues without checking project context:
gh issue create --title "Add feature" --label "feature"

✅ CORRECT - Check env.json first, then add to project:
# 1. Check context
cat .claude/github-workflows/env.json | grep projectBoard

# 2. Create issue
gh issue create --title "Add feature" --label "feature"

# 3. Add to project
gh project item-add 3 --owner OWNER --url ISSUE_URL

Why it matters: Issues not added to project boards lose visibility and don't appear in sprint planning or roadmaps.

Mistake 3: Not Asking Clarifying Questions

❌ WRONG - Jumping straight to issue creation:
User: "Create issues for the new auth feature"
Claude: *immediately creates 5 issues*

✅ CORRECT - Ask clarifying questions first:
User: "Create issues for the new auth feature"
Claude: "Before I create these issues, let me confirm:
1. Should I add them to project #3?
2. Should the main feature issue be parent of the subtasks?
3. Should they be assigned to the v1.0 milestone?"

Why it matters: 5 minutes of clarification saves 30 minutes of corrections. Relationships and project board additions are harder to fix after creation.

Mistake 4: Ignoring IDE Context Signals

❌ WRONG - Ignoring that user has env.json open:
&#x3C;ide_opened_file>env.json&#x3C;/ide_opened_file>
Claude: *doesn't read env.json*

✅ CORRECT - Read files the user has open:
&#x3C;ide_opened_file>env.json&#x3C;/ide_opened_file>
Claude: *reads env.json to get project board, milestone, etc.*

Why it matters: Files open in the user's IDE are intentional signals. They often contain critical context for the task.

Mistake 5: Creating Issues Without Verification

❌ WRONG - Creating and moving on:
gh issue create ...
"Done! Created issue #67"

✅ CORRECT - Verify after creation:
gh issue create ...
gh issue view 67 --json labels,projectItems
python manage-relationships.py show-all --issue 67
"Created #67, added to project #3, linked as child of #50"

Why it matters: External-facing work needs verification. It's easier to catch mistakes immediately than fix them later.

Mistake 6: Missing Required Labels

❌ WRONG - Only type label:
--label "feature"

✅ CORRECT - All three required labels:
--label "feature,priority:medium,scope:self-improvement"

Why it matters: Scope labels enable context-aware filtering in /issue-track context
 and automatic issue detection in /commit-smart
.

Pre-Flight Checklist

Before creating ANY issue, verify:

Context Gathering

-  Checked env.json
 for project board number

-  Checked env.json
 for milestone info

-  Checked user's open IDE files for signals

-  Identified scope from branch or project structure

Clarifying Questions (for complex requests)

-  Confirmed project board assignment

-  Confirmed parent-child relationships

-  Confirmed milestone assignment

-  Confirmed scope if not auto-detected

Issue Content

-  Title follows conventions (no prefix, imperative mood)

-  All three required labels (type, priority, scope)

-  Structured body with acceptance criteria

-  Parent reference in body if applicable

Post-Creation

-  Added to project board

-  Established parent-child relationships via GraphQL

-  Verified all metadata is correct

-  Reported results to user with links

creating-issues

Safety Notice

Copy this and send it to your AI assistant to learn

Summary

Acceptance Criteria

Additional Context

Summary

Steps to Reproduce

Expected Behavior

Actual Behavior

Acceptance Criteria

Environment

Summary

Use Cases

Proposed Solution

Acceptance Criteria

Out of Scope

After creating issues, establish parent-child relationships

Parent Issue

Blocked By

Related Issues

Check if env.json exists with project info

Add issue to project board

Summary

Problem

Source Transparency

Related Skills

investigating-codebases

writing-docs

managing-docs