GitHub Create Issue Skill

Create GitHub issues using the best available tool with intelligent template matching.

When to Use This Skill

Use this skill when you need to:

• Create a new GitHub issue in the current repository
• Apply matching issue templates from .github/ISSUE_TEMPLATE/
• Add metadata like labels, assignees, milestones, or projects
• Automatically determine the right tool (MCP Server, CLI, or REST API)

Quick Start

Basic Issue Creation

Create a GitHub issue titled "App crashes on startup" with body "The app crashes immediately after launching on Windows 10"

The skill will:

1. Check for available templates matching "crashes on startup"
2. Suggest bug template if available
3. Create the issue using the best available tool

With Metadata

Create a GitHub issue titled "Add dark mode support" labeled as "enhancement,ui" assigned to @sarah with the feature template

Workflow

Phase 1: Template Detection

The skill scans .github/ISSUE_TEMPLATE/ for available templates:

• Supports .md (Markdown) and .yml/.yaml (YAML) formats
• Extracts template names, metadata, and content
• Works with any template structure or naming convention

Phase 2: Intelligent Matching

When issue description is provided, the skill matches it to templates:

• Extracts meaningful keywords from each template's filename and metadata
• Scores templates based on keyword overlap with issue description
• Auto-selects template if one clearly matches (score significantly higher than others)
• Presents all available options to user if scores are ambiguous or no clear match

This approach works with any template type—templates are matched by their own names and metadata, not by predefined issue categories.

Phase 3: Issue Creation

Uses tools in order of precedence:

1. GitHub MCP Server (when in Claude context with GitHub tools available)
2. GitHub CLI (gh command, requires authentication)
3. GitHub REST API (requires GITHUB_TOKEN environment variable)

The skill attempts each tool until one succeeds.

Tool Selection Details

GitHub CLI (gh)

Best for: Interactive workflows, local development, pre-existing auth

Requirements:

• gh command installed
• Authenticated via gh auth login

Supports: title, body, labels, assignees, milestone

GitHub REST API

Best for: CI/CD, automation, programmatic access

Requirements:

• GITHUB_TOKEN or GH_TOKEN environment variable
• Token must have repo scope

Supports: title, body, labels, assignees, milestone

Note: Projects require a separate API call after issue creation

GitHub MCP Server

Best for: Integrated Claude workflows

Requirements: Claude with GitHub MCP Server enabled

Supports: All fields including projects

Template Format Examples

Markdown Template

---
name: Bug Report
title: "[Bug]: "
description: "Report a bug"
labels: ["bug"]
---

## Describe the bug
[Description here]

## Steps to reproduce
1. Step one
2. Step two

YAML Template

name: Feature Request
description: Suggest an enhancement
labels: ["enhancement"]
assignees: ["lead-dev"]

Configuration

Environment Variables

# GitHub CLI authentication (handled by gh auth login)
# No manual setup needed

# REST API authentication
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# or
export GH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Repository Detection

The skill automatically detects:

• Repository owner and name from git remote URL
• Current directory as repository root (can be overridden)

Common Scenarios

Scenario 1: Simple Template Matching

User Input: "Create issue: App won't start on macOS"

Flow:

1. Finds all templates in .github/ISSUE_TEMPLATE/
2. Scores templates by keyword match (looks for words in template names/metadata)
3. If strong match found (e.g., template named "bug-report"), suggests it
4. Creates issue with selected template

Scenario 2: Multiple Equally Relevant Templates

User Input: "New feature: support environment variables"

Flow:

1. Finds multiple templates that could apply
2. Displays options: "Which template? 1) Enhancement 2) Feature Request 3) Other"
3. Uses selected template
4. Creates issue

Scenario 3: Custom Template Types

User Input: "Create issue for security concern"

Flow:

1. Finds templates including custom ones (e.g., "security-disclosure", "vulnerability-report")
2. Matches based on template name and metadata
3. Suggests best match or presents options
4. Creates issue with matched template

Scenario 4: No Templates Available

User Input: "Create a quick issue"

Flow:

1. No templates in .github/ISSUE_TEMPLATE/
2. Creates issue directly with just title and body

Scenario 5: Tool Fallback

User Input: Create issue (gh CLI not installed)

Flow:

1. Detects gh CLI unavailable
2. Attempts GitHub REST API
3. Checks for GITHUB_TOKEN environment variable
4. Falls back with error if neither tool available

Reference

For detailed information about:

• GitHub API and CLI options: See api-guide.md
• Template matching algorithm details: See template_matcher.py
• Issue creation implementation: See issue_creator.py

Error Handling

The skill handles these common errors gracefully:

Error	Solution
"gh: not found"	Install GitHub CLI from https://cli.github.com
"Not authenticated"	Run gh auth login to authenticate
"GITHUB_TOKEN not set"	Set GITHUB_TOKEN environment variable
"Repository not found"	Verify git remote is configured correctly
"Invalid labels"	Check that labels exist in the repository

Integration Example

When using this skill in Claude tasks:

I need to create a GitHub issue for the current bug we found. 
The issue should mention that the API timeout is causing data loss.
Apply the appropriate template and create it.

The skill will:

1. Scan for all templates in .github/ISSUE_TEMPLATE/
2. Match templates based on their names and metadata (not hardcoded categories)
3. Suggest best matching template or present options
4. Create the issue using available tools
5. Return issue URL or error details

Or with custom template types:

Create a security issue about a potential XSS vulnerability

If the repository has custom templates like "security-disclosure" or "vulnerability-report", the skill will intelligently match based on the template names themselves.