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

1. Issue-to-Swarm Conversion

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

# Analyze issue complexity
BODY=$(echo "$ISSUE" | jq -r '.body')
LABEL_COUNT=$(echo "$ISSUE" | jq '.labels | length')
COMMENT_COUNT=$(echo "$ISSUE" | jq '.comments | length')

# 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..."

2. 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"

3. 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

4. Issue Comment Commands

Use these commands in issue comments:

<!-- Analyze issue and suggest approach -->
/swarm analyze

<!-- Decompose into subtasks -->
/swarm decompose 5

<!-- Assign specific agent type -->
/swarm assign @coder

<!-- Estimate effort -->
/swarm estimate

<!-- Start swarm processing -->
/swarm start

<!-- Check progress -->
/swarm progress

<!-- Complete and summarize -->
/swarm complete

5. Automated Triage

# Triage unlabeled issues
triage_issues() {
  # Get unlabeled issues
  gh issue list --label "" --json number,title,body | \
    jq -r '.[] | @base64' | while read -r encoded; do
      ISSUE=$(echo "$encoded" | base64 -d)
      NUM=$(echo "$ISSUE" | jq -r '.number')
      TITLE=$(echo "$ISSUE" | jq -r '.title')
      BODY=$(echo "$ISSUE" | jq -r '.body')

      # 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

6. 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" \< "$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:**
1. Reproduce the bug
2. Isolate to minimal case
3. Identify root cause
4. Implement fix
5. Add regression tests
6. 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:**
1. Design review
2. Implementation
3. Testing
4. Documentation
5. Demo/Review"
}

Best Practices

1. Issue Templates

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

2. Label Strategy

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

3. Comment Etiquette

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

4. 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