name	github-issue-creator
description	Create GitHub issues across any repository with proper formatting, labels, and project board assignment. Use when mentions "create issue", "GitHub issue", "open issue", "file issue", "report bug", "feature request".
allowed-tools	Bash, Read, Write

GitHub Issue Creator Skill

Create well-formatted GitHub issues across any repository with automatic project board assignment and Claude Code attribution.

Capabilities

Multi-repository support: Create issues in any accessible GitHub repository
Flexible input: Command-line flags, interactive mode, or file-based body
Template support: Use predefined templates (bug, feature, idea, etc.)
Project integration: Automatically add to project boards
Label management: Apply multiple labels for categorization
Assignment: Assign to yourself or team members
Claude attribution: Automatic footer attribution

Script Location

Main Script: scripts/create-github-issue.sh

This is a DRY, SOLID, KISS implementation that can be reused across:

Different repositories
Different GitHub organizations
Different users
Different issue types

Usage Modes

1. Quick Issue Creation

# Create issue in current repo
./scripts/create-github-issue.sh \
    -t "Fix authentication timeout" \
    -l "bug,urgent" \
    -b "Users experiencing timeouts after 5 minutes"

# Create feature request
./scripts/create-github-issue.sh \
    -t "Add dark mode support" \
    -l "enhancement,ui" \
    -a "@me"

2. Cross-Repository Issues

# Create issue in different repo
./scripts/create-github-issue.sh \
    -r your-org/your-repo \
    -t "Update documentation" \
    -l "docs" \
    -a @me

# Create issue with project board assignment
./scripts/create-github-issue.sh \
    -r ijack-technologies/planning \
    -t "Q1 2026 Planning" \
    -p 12 \
    -l "epic,planning"

3. Interactive Mode

# Prompt for all fields
./scripts/create-github-issue.sh -i

# Interactive prompts:
# - Repository (defaults to current)
# - Title (required)
# - Labels (optional)
# - Assignee (defaults to @me)
# - Body (supports markdown, Ctrl+D when done)
# - Project ID (optional)

4. File-Based Body

# Use markdown file for issue body
./scripts/create-github-issue.sh \
    -t "Database migration plan" \
    -f docs/migration-plan.md \
    -l "database,migration" \
    -p 12

Command-Line Options

Flag	Long Form	Description	Default
`-r`	`--repo`	Repository (owner/name)	Current repo
`-t`	`--title`	Issue title	Required
`-b`	`--body`	Issue body (markdown)	Empty
`-f`	`--body-file`	Read body from file	-
`-l`	`--labels`	Comma-separated labels	None
`-a`	`--assignee`	Username or @me	Current user (dynamic)
`-p`	`--project`	Project board ID	None
`-T`	`--template`	Template name	None
`-i`	`--interactive`	Interactive mode	False
`-h`	`--help`	Show help	-

Dynamic Username Detection

CRITICAL: NEVER hard-code GitHub usernames in examples or default values.

# Get current GitHub username dynamically
GITHUB_USER=$(gh api user --jq '.login')

# Use in issue creation
gh issue create --title "Fix bug" --assignee "$GITHUB_USER" --body "..."

# Or let the script handle it automatically (recommended)
gh issue create --title "Fix bug" --assignee "@me" --body "..."

Why this matters:

Repository is used by multiple team members
Hard-coded usernames break when others use the scripts
@me or dynamic detection ensures it works for everyone

Query Available Labels

CRITICAL: ALWAYS query available labels before creating issues to avoid "label not found" errors.

# Query available labels FIRST
gh label list --json name,description,color

# Example output:
# [
#   {"name":"bug","description":"Something isn't working","color":"d73a4a"},
#   {"name":"enhancement","description":"New feature or request","color":"a2eeef"},
#   {"name":"documentation","description":"Improvements or additions to documentation","color":"0075ca"},
#   {"name":"question","description":"Further information is requested","color":"d876e3"}
# ]

# Extract just the label names for easy reference
gh label list --json name --jq '.[].name'
# Output: bug, enhancement, documentation, question, etc.

# Now create issue with ONLY labels that exist
gh issue create \
    --title "Fix authentication timeout" \
    --label "bug" \
    --assignee "$GITHUB_USER" \
    --body "..."

Label Validation Workflow:

Query available labels: gh label list --json name
Verify your desired labels exist in the output
Only use labels that are available
If needed label doesn't exist, either:
- Use an alternative existing label
- Create the new label first: gh label create "new-label" --description "Description" --color "FF0000"

Why this matters:

Different repositories have different label sets
Avoids issue creation failures due to missing labels
Ensures consistent labeling practices across repositories
Prevents typos in label names

Issue Templates

Available templates (future enhancement):

bug: Bug report format
feature: Feature request format
idea: Idea/enhancement format
service: Service request format
user-story: User story format
epic: Epic/large initiative format

Common Workflows

Bug Report

./scripts/create-github-issue.sh \
    -t "🐛 Gateway crashes on startup" \
    -l "bug,critical" \
    -b "$(cat <<'EOF'
## Description
Gateway crashes immediately after startup on Axiomtek devices.

## Steps to Reproduce
1. Deploy version 3.334225
2. Restart gateway
3. Observe crash in logs

## Expected Behavior
Gateway starts successfully and connects to MQTT broker.

## Actual Behavior
Process exits with code 1 after 3 seconds.

## Environment
- Gateway: Axiomtek ICO300-83C
- Version: 3.334225
- OS: Ubuntu 22.04
EOF
)"

Feature Request

./scripts/create-github-issue.sh \
    -t "📍 Add GPS coordinates to device shadow" \
    -l "enhancement,feature" \
    -p 12 \
    -b "$(cat <<'EOF'
## Feature Description
Add GPS coordinates (latitude, longitude) to device shadow for location tracking.

## Use Case
Operations team needs to verify gateway physical location matches database records.

## Proposed Solution
1. Add GPS module reading to `canpy/sensors/gps.py`
2. Update device shadow schema
3. Display location on web dashboard map

## Acceptance Criteria
- [ ] GPS coordinates read from hardware
- [ ] Coordinates published to device shadow
- [ ] Web dashboard shows location on map
- [ ] Location updates every 5 minutes
EOF
)"

Idea/Enhancement

./scripts/create-github-issue.sh \
    -t "💡 Implement alert deduplication with PostgreSQL" \
    -l "idea,enhancement" \
    -b "$(cat <<'EOF'
## Problem
File-based alert deduplication fails when SD card corrupts, causing duplicate alerts.

## Proposed Solution
Use PostgreSQL database for robust alert deduplication with ACID guarantees.

## Benefits
- Survives SD card failures
- Centralized tracking
- Easier monitoring
- Better reliability
EOF
)"

Integration with IJACK Roadmap

For IJACK Technologies projects, always add issues to Project #12 (IJACK Roadmap):

# Create issue and add to roadmap automatically
./scripts/create-github-issue.sh \
    -r ijack-technologies/rcom \
    -t "Implement cellular failover" \
    -l "enhancement,networking" \
    -p 12 \
    -a "@me"

Manual Project Addition (if automatic fails):

# Get issue URL from output, then:
gh project item-add 12 --owner ijack-technologies --url <ISSUE_URL>

User Trigger Examples

Claude will activate this skill when you say:

"Create a GitHub issue"
"File a bug report"
"Open an issue for this"
"Create feature request issue"
"Report this bug on GitHub"
"Make an issue in repo X"
"File an issue about the duplicate alerts"

Skill Activation Process

When triggered, Claude will:

Analyze context: Determine if current work should be documented as issue
Extract information: Pull relevant details from conversation
Choose repository: Use current repo or ask which one
Query available labels: Run gh label list --json name to see which labels exist
Determine GitHub username: Run gh api user --jq '.login' to get current user
Format issue: Create well-structured title and body
Apply labels: Add appropriate labels ONLY from the available labels list
Execute script: Run create-github-issue.sh with correct parameters
Add to project board: Add to IJACK Roadmap (Project #12) if applicable
Confirm creation: Return issue URL and next steps

Best Practices

Issue Titles

✅ Good Titles:

"Fix: Database connection timeout after 5 minutes"
"Feature: Add real-time alert dashboard"
"Bug: Gateway fails to reconnect after network outage"
"Idea: Implement predictive maintenance ML model"

❌ Bad Titles:

"Fix bug" (too vague)
"Add feature" (not descriptive)
"Problem" (no context)
"Help needed" (unclear)

Issue Bodies

Include:

Clear description
Steps to reproduce (for bugs)
Expected vs actual behavior
Environment details
Acceptance criteria (for features)
References to related issues/PRs

Avoid:

Vague descriptions
Missing context
No action items
Duplicate information

Labels

IMPORTANT: Always query available labels FIRST before using them:

# Query available labels in the repository
gh label list --json name --jq '.[].name'

Common label categories (but verify they exist in your repo):

Type: bug, enhancement, feature, idea, documentation
Priority: urgent, high, medium, low, critical
Component: database, networking, alerts, ui
Status: blocked, in-progress, needs-review, help wanted

Best practices:

ONLY use labels that exist in the repository (query first!)
Use multiple labels to provide better context (e.g., bug,database,urgent)
Prefer standard GitHub labels when available (bug, enhancement, documentation)
If a needed label doesn't exist, create it first or use an alternative

Examples from Real Usage

Example 1: Current Session

From the duplicate alerts work, this would create:

./scripts/create-github-issue.sh \
    -r ijack-technologies/rcom \
    -t "Implement database-backed alert deduplication" \
    -l "enhancement,database,alerts" \
    -p 12 \
    -b "$(cat <<'EOF'
## Problem
File-based alert deduplication fails when SD card corrupts, causing duplicate alerts every 3-6 minutes.

## Solution
Implement PostgreSQL-backed deduplication with automatic migration from file-based timestamps.

## Implementation
- Database table: public.alert_deduplication
- Migration script: 001_alert_deduplication_table.sql
- Automatic one-time migration on first check
- Fail-safe: Don't send if DB unavailable

## Files Changed
- canpy/alerts/alert_deduplication.py (new)
- canpy/alerts/egas.py (updated)
- canpy/alerts/warn.py (updated)
- test/test_fast/test_alert_deduplication.py (23 tests)

## Status
✅ Implementation complete
✅ All tests passing
✅ Ready for deployment
EOF
)"

Example 2: Cross-User Usage

Example: Creating issue in different repository:

./scripts/create-github-issue.sh \
    -r your-org/your-repo \
    -t "Add pytest fixtures for database tests" \
    -l "testing,enhancement" \
    -a @me \
    -b "Standardize database fixtures across test suite"

Script Design Principles

DRY (Don't Repeat Yourself)

Single script handles all issue types
Reusable across repositories
Common functions (auth check, validation, formatting)

SOLID

Single Responsibility: Only creates issues (doesn't modify, close, etc.)
Open/Closed: Extensible via templates and flags
Liskov Substitution: Works consistently across repos
Interface Segregation: Clear, focused command-line interface
Dependency Inversion: Depends on gh CLI abstraction

KISS (Keep It Simple)

Clear command-line flags
Sensible defaults
One task per execution
Helpful error messages

Troubleshooting

Authentication Issues

# Check authentication
gh auth status

# Re-authenticate if needed
gh auth login --web

Repository Not Found

# Verify repo exists and you have access
gh repo view owner/repo

# Check repository name format
# Correct: ijack-technologies/rcom
# Wrong: gateway-can-to-mqtt (missing owner)

Project Board Issues

# List available projects
gh project list --owner ijack-technologies

# Manually add to project
gh project item-add 12 --owner ijack-technologies --url <ISSUE_URL>

Advanced Usage

Batch Issue Creation

# Create multiple issues from a list
while IFS='|' read -r title labels body; do
    ./scripts/create-github-issue.sh -t "$title" -l "$labels" -b "$body"
done < issues.txt

CI/CD Integration

# Create issue from test failures in CI
if [[ $TEST_EXIT_CODE -ne 0 ]]; then
    ./scripts/create-github-issue.sh \
        -t "🚨 CI Test Failure: $GITHUB_SHA" \
        -l "bug,ci,automated" \
        -b "Test suite failed on commit $GITHUB_SHA"
fi

Related Skills

smart-committer: Create commits before filing issues
pr-creator: Convert issues into pull requests
github-actions-monitor: Track CI/CD for issue-related changes
technical-report-generator: Generate detailed issue bodies

Success Metrics

✅ Works across multiple repositories
✅ Supports different GitHub users
✅ Handles interactive and scripted modes
✅ Integrates with project boards
✅ Consistent formatting with Claude attribution
✅ Clear error messages and help text

This skill uses the generic scripts/create-github-issue.sh script following DRY, SOLID, and KISS principles.

Install Skill

SKILL.md