GitHub Swarm Issue Skill

Overview

This skill transforms GitHub Issues into intelligent swarm tasks, enabling automatic task decomposition, agent coordination, and comprehensive progress tracking. It provides issue-to-swarm conversion, automated triage, and lifecycle management.

Key Capabilities:

Issue-to-swarm conversion with automatic decomposition
Issue comment commands for swarm control
Automated triage and labeling
Task breakdown with subtask creation
Progress tracking with visual updates
Duplicate detection and linking

Quick Start

Get issue details for swarm initialization

gh issue view 456 --json title,body,labels,assignees,comments

List issues ready for swarm processing

gh issue list --label "swarm-ready"

Add swarm label to trigger processing

gh issue edit 456 --add-label "swarm-ready"

Post swarm status comment

gh issue comment 456 --body "Swarm initialized for this issue"

When to Use

Complex Issues: Multi-step tasks requiring decomposition
Bug Investigation: Issues needing systematic debugging
Feature Requests: New features requiring architecture and implementation
Technical Debt: Refactoring tasks with multiple components
Epic Management: Coordinating child issues under parent

Usage Examples

Issue-to-Swarm Conversion

Get complete issue context

ISSUE=$(gh issue view 456 --json title,body,labels,assignees,comments,projectItems)

Analyze issue complexity

Determine swarm topology based on complexity

if [ $LABEL_COUNT -gt 3 ] || [ ${#BODY} -gt 1000 ]; then TOPOLOGY="hierarchical" MAX_AGENTS=8 elif echo "$BODY" | grep -qE "([ ]|1.|step)" ; then TOPOLOGY="mesh" MAX_AGENTS=5 else TOPOLOGY="ring" MAX_AGENTS=3 fi

echo "Issue #456: Using $TOPOLOGY topology with $MAX_AGENTS agents"

Initialize swarm comment

gh issue comment 456 --body "## Swarm Initialized

Topology: $TOPOLOGY Agents: $MAX_AGENTS

Processing issue for task decomposition..."

Task Decomposition

Get issue body

ISSUE_BODY=$(gh issue view 456 --json body --jq '.body')

Extract tasks from issue body (markdown checklist items)

TASKS=$(echo "$ISSUE_BODY" | grep -E '^\s*-\s*[ ]' | sed 's/.*[ ]//')

Create subtask checklist

SUBTASK_LIST="" TASK_NUM=1 echo "$TASKS" | while read -r task; do SUBTASK_LIST+="- [ ] $TASK_NUM. $task\n" TASK_NUM=$((TASK_NUM + 1)) done

Update issue with structured subtasks

UPDATED_BODY="$ISSUE_BODY

Swarm Task Breakdown

$SUBTASK_LIST

Decomposed by Swarm Agent"

gh issue edit 456 --body "$UPDATED_BODY"

Create linked issues for major subtasks

gh issue create
--title "Subtask: Implement authentication"
--body "Part of #456

Task

Implement the authentication module.

Acceptance Criteria

User login works
Token refresh works
Logout clears session"
--label "subtask"

Progress Tracking

Track issue progress

track_progress() { local ISSUE_NUM=$1

Get current issue state

ISSUE=$(gh issue view $ISSUE_NUM --json body,labels) BODY=$(echo "$ISSUE" | jq -r '.body')

Count completed vs total tasks

TOTAL=$(echo "$BODY" | grep -cE '^\s*-\s*[[ x]]' || echo 0) COMPLETED=$(echo "$BODY" | grep -cE '^\s*-\s*[x]' || echo 0) PERCENT=$((COMPLETED * 100 / TOTAL))

Generate progress bar

FILLED=$((PERCENT / 5)) EMPTY=$((20 - FILLED)) PROGRESS_BAR=$(printf '█%.0s' $(seq 1 $FILLED))$(printf '░%.0s' $(seq 1 $EMPTY))

Post progress update

gh issue comment $ISSUE_NUM --body "## Progress Update

Completion: $PERCENT% [$PROGRESS_BAR] Tasks: $COMPLETED / $TOTAL completed

$([ $PERCENT -eq 100 ] && echo '✅ All tasks complete!' || echo '🔄 Work in progress...')

Updated: $(date '+%Y-%m-%d %H:%M')" }

track_progress 456

Issue Comment Commands

Use these commands in issue comments:

/swarm analyze

/swarm decompose 5

/swarm assign @coder

/swarm estimate

/swarm start

/swarm progress

/swarm complete

Automated Triage

Triage unlabeled issues

triage_issues() {

Get unlabeled issues

  # Analyze content for auto-labeling
  LABELS=""

  # Bug detection
  if echo "$TITLE $BODY" | grep -qiE "bug|error|broken|crash|fail"; then
    LABELS="bug"
  fi

  # Feature detection
  if echo "$TITLE $BODY" | grep -qiE "feature|add|implement|new"; then
    LABELS="${LABELS:+$LABELS,}enhancement"
  fi

  # Performance detection
  if echo "$TITLE $BODY" | grep -qiE "slow|performance|optimize|speed"; then
    LABELS="${LABELS:+$LABELS,}performance"
  fi

  # Security detection
  if echo "$TITLE $BODY" | grep -qiE "security|vulnerability|auth|permission"; then
    LABELS="${LABELS:+$LABELS,}security"
  fi

  # Apply labels
  if [ -n "$LABELS" ]; then
    gh issue edit $NUM --add-label "$LABELS"
    echo "Issue #$NUM: Added labels $LABELS"
  fi
done

}

triage_issues

Stale Issue Management

Process stale issues

manage_stale_issues() {

Get issues not updated in 30 days

STALE_DATE=$(date -d '30 days ago' '+%Y-%m-%d')

gh issue list --state open --json number,title,updatedAt |
jq -r ".[] | select(.updatedAt < "$STALE_DATE") | .number" |
while read -r num; do # Check if already marked stale LABELS=$(gh issue view $num --json labels --jq '.labels[].name')

  if echo "$LABELS" | grep -q "stale"; then
    # Already stale for 7+ days - close
    STALE_CHECK=$(date -d '7 days ago' '+%Y-%m-%d')
    UPDATED=$(gh issue view $num --json updatedAt --jq '.updatedAt[:10]')

    if [ "$UPDATED" \&#x3C; "$STALE_CHECK" ]; then
      gh issue close $num --comment "Closing due to inactivity. Feel free to reopen if still relevant."
    fi
  else
    # Mark as stale
    gh issue edit $num --add-label "stale"
    gh issue comment $num --body "This issue has been inactive for 30 days. It will be closed in 7 days if there's no activity."
  fi
done

}

manage_stale_issues

Issue Templates for Swarms

.github/ISSUE_TEMPLATE/swarm-task.yml

name: Swarm Task description: Create a task for AI swarm processing body:

type: dropdown id: topology attributes: label: Swarm Topology options: - mesh (collaborative) - hierarchical (structured) - ring (sequential) - star (centralized) validations: required: true
type: input id: agents attributes: label: Required Agents placeholder: "coder, tester, analyst"
type: textarea id: description attributes: label: Task Description placeholder: "Describe what needs to be done..." validations: required: true
type: textarea id: subtasks attributes: label: Subtasks (Optional) placeholder: | - [ ] Subtask 1 - [ ] Subtask 2 - [ ] Subtask 3

MCP Tool Integration

Multi-Agent Issue Processing

// Initialize issue-specific swarm

// Store issue context in swarm memory action: "store", key: "issue/456/context", value: { issue_number: 456, title: "Implement authentication", labels: ["feature", "priority:high"], complexity: "high", agents_assigned: ["coordinator", "analyst", "coder", "tester"] } }

// Orchestrate issue resolution task: "Coordinate multi-agent issue resolution with progress tracking", strategy: "adaptive", priority: "high" }

GitHub Integration Tools

// Track issues repo: "owner/repo", action: "triage" }

// Analyze repository repo: "owner/repo", analysis_type: "code_quality" }

// Get metrics repo: "owner/repo" }

GitHub Actions Integration

.github/workflows/issue-swarm.yml

name: Issue Swarm Handler on: issues: types: [opened, labeled] issue_comment: types: [created]

jobs: process-new-issue: if: github.event.action == 'opened' runs-on: ubuntu-latest steps: - name: Auto-Triage Issue env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | TITLE="${{ github.event.issue.title }}" BODY="${{ github.event.issue.body }}"

      # Determine labels based on content
      LABELS=""
      if echo "$TITLE $BODY" | grep -qiE "bug|error"; then
        LABELS="bug"
      elif echo "$TITLE $BODY" | grep -qiE "feature|add"; then
        LABELS="enhancement"
      fi

      if [ -n "$LABELS" ]; then
        gh issue edit ${{ github.event.issue.number }} --add-label "$LABELS"
      fi

handle-swarm-label: if: github.event.action == 'labeled' && github.event.label.name == 'swarm-ready' runs-on: ubuntu-latest steps: - name: Initialize Swarm env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | gh issue comment ${{ github.event.issue.number }}
--body "## Swarm Processing Started

      This issue has been queued for swarm processing.

      **Status**: Analyzing...
      **ETA**: ~15 minutes"

handle-commands: if: github.event_name == 'issue_comment' && startsWith(github.event.comment.body, '/swarm') runs-on: ubuntu-latest steps: - name: Process Command run: | COMMAND="${{ github.event.comment.body }}" echo "Processing swarm command: $COMMAND"

Issue Types and Strategies

Bug Reports

Specialized bug handling

handle_bug() { local ISSUE_NUM=$1

gh issue comment $ISSUE_NUM --body "## Bug Investigation Swarm

Agents Assigned:

Debugger: Reproduce and isolate
Analyst: Root cause analysis
Tester: Regression tests
Coder: Fix implementation

Process:

Reproduce the bug
Isolate to minimal case
Identify root cause
Implement fix
Add regression tests
Verify fix" }

Feature Requests

Feature implementation workflow

handle_feature() { local ISSUE_NUM=$1

gh issue comment $ISSUE_NUM --body "## Feature Implementation Swarm

Agents Assigned:

Architect: Design approach
Coder: Implementation
Tester: Test coverage
Reviewer: Code quality

Phases:

Design review
Implementation
Testing
Documentation
Demo/Review" }

Best Practices

Issue Templates

Include swarm configuration options
Provide structured task breakdown
Set clear acceptance criteria
Include complexity estimates

Label Strategy

Use consistent swarm-related labels (swarm-ready, swarm-processing)
Map labels to agent types
Include priority indicators
Track status with labels

Comment Etiquette

Clear command syntax (/swarm command)
Progress updates in threads
Summary comments for decisions
Link to relevant PRs

Progress Tracking

Regular status updates
Visual progress indicators
ETA estimates
Blocker identification

Metrics and Analytics

Issue resolution metrics

generate_metrics() {

Get closed issues from last 30 days

gh issue list --state closed --json number,title,createdAt,closedAt,labels |
jq '{ total_closed: length, avg_resolution_days: ([.[].createdAt, .[].closedAt] | map(fromdateiso8601) | . as $dates | (($dates[1] - $dates[0]) / 86400)) | add / length, by_label: group_by(.labels[].name) | map({label: .[0].labels[0].name, count: length}) }' }

generate_metrics

Related Skills

github-swarm-pr - PR-based swarm coordination
github-project-board - Project board integration
github-workflow - CI/CD automation
github-modes - GitHub integration modes

Version History

1.0.0 (2026-01-02): Initial skill conversion from swarm-issue agent

github-swarm-issue

Safety Notice

Copy this and send it to your AI assistant to learn