name	github-issue-manager
description	Comprehensive GitHub issue management with AI-powered classification, smart templates, bi-directional vault sync, and orchestrated workflows. Supports feature, bug, chore, and enhancement issue types.
license	MIT
metadata	[object Object]

GitHub Issue Manager Skill v2.0

Orchestrated Workflow Edition - Inspired by ADW (AI Developer Workflow)

Purpose

This skill provides comprehensive GitHub issue management with bi-directional vault synchronization, combining AI-powered classification, smart templates, and orchestrated workflows.

Key Features:

✅ AI-Powered Classification - Automatically determine issue type and recommend labels
✅ Smart Templates - Context-rich templates for feature, bug, chore, enhancement
✅ Bi-Directional Sync - Keep vault tasks and GitHub issues in sync
✅ State Management - Track issue creation, updates, and sync status
✅ Dependency Tracking - Automatically link related issues
✅ Orchestrated Workflows - Automated issue creation from planning specs
✅ Progress Tracking - Know what's created, synced, and in progress

When to Use This Skill

Activate this skill when you need to:

Create GitHub issues from planning documents (spec-planning integration)
Quickly create well-structured issues during development
Sync vault tasks with GitHub issues (bi-directional)
Classify existing issues and add proper labels
Track dependencies between issues
Manage team coordination through GitHub

Trigger Phrases:

"Create GitHub issues from my planning docs"
"Sync my vault tasks with GitHub"
"Create a feature/bug/chore issue for [description]"
"Classify this issue and recommend labels"
"Track dependencies for [issue/task]"

Issue Types Supported

See: Issue Types Reference

The skill supports four distinct issue types, each with specialized templates and workflow patterns:

1. Feature (New Functionality)

Complete user stories with acceptance criteria, implementation notes, and time estimates.

Template: templates/feature-issue.md Labels: type-feature, priority-*, estimate-*, phase-*

2. Bug (Defect/Error)

Bug reports with reproduction steps, expected/actual behavior, and debugging context.

Template: templates/bug-issue.md Labels: type-bug, priority-*, severity-*, status-*

3. Chore (Maintenance)

Technical debt, refactoring, dependency updates, infrastructure changes.

Template: templates/chore-issue.md Labels: type-chore, priority-*, estimate-*, category-*

4. Enhancement (Improvement)

Improvements to existing features, performance optimizations, UX refinements.

Template: templates/enhancement-issue.md Labels: type-enhancement, priority-*, estimate-*, impact-*

Orchestrated Workflows

Workflow 1: Create Issue from Description

See: Workflow 1 Details

Trigger: User provides issue description Duration: 2-5 minutes

Creates a well-structured GitHub issue from a simple description using AI classification, smart template filling, label recommendation, and dependency detection.

Key Steps:

AI Classification - Determine type (feature/bug/chore/enhancement)
Template Selection - Load appropriate template
Smart Filling - AI fills template fields
Label Recommendation - Suggest priority, estimate, category
Dependency Detection - Find related issues
GitHub Creation - Create via MCP
Vault Sync - Create corresponding task (optional)
State Update - Track in state file

Example:

Input: "Create a feature for dark mode toggle"
Output: Issue #123 with complete feature template

Workflow 2: Sync Vault Task to GitHub

See: Workflow 2 Details

Trigger: User has vault task without GitHub issue Duration: 2-3 minutes

Converts vault GTD task to GitHub issue with proper field mapping and label transformation.

Key Steps:

Load Vault Task - Read metadata
Classify Type - Determine issue type from task
Transform to Issue - Map GTD fields to GitHub fields
Create on GitHub - Create via MCP
Update Vault Task - Add github_issue link
State Update - Track sync relationship

Field Mappings: status, priority, contexts, timeEstimate → GitHub labels

Workflow 3: Sync GitHub Issue to Vault

See: Workflow 3 Details

Trigger: GitHub issue exists without vault task Duration: 2-3 minutes

Imports GitHub issue as vault task with GTD-compatible metadata.

Key Steps:

Fetch Issue - Get via MCP
Classify Type - Determine task type
Transform to Task - Map GitHub fields to GTD
Create Vault Task - Save to 05 Tasks/
Link Entities - Add github_issue to metadata
State Update - Track sync relationship

Field Mappings: GitHub labels → status, priority, contexts, timeEstimate

Workflow 4: Batch Issue Creation (from Planning Docs)

See: Workflow 4 Details

Trigger: User has development stories or planning docs Duration: 5-15 minutes (depends on story count)

Creates multiple issues from planning documents with dependency tracking and milestone management.

Key Steps:

Parse Planning Docs - Extract stories/tasks
Classify All Stories - Determine types in batch
Detect Dependencies - Build dependency graph
Create Milestones - Group by phase/sprint
Create Issues - In dependency order
Link Dependencies - Add issue references
Create Vault Tasks - Sync all (if enabled)
Generate Summary - Report creation results

Example:

Input: development-stories.md (15 stories)
Output: 15 GitHub issues, 3 milestones, 8 dependencies linked

AI Decision Points

See: AI Decision Points Reference

The skill uses AI at six critical moments to automate decisions:

1. Classify Issue Type

Analyze description keywords and patterns to determine feature/bug/chore/enhancement with 0-100% confidence.

2. Recommend Labels

Suggest priority (critical/high/medium/low), time estimate (1h/2h/4h/8h/2d/1w), and categories based on content analysis.

3. Detect Dependencies

Find explicit references ("Depends on #123") and implicit dependencies through keyword matching.

4. Generate Branch Name

Create semantic names: {type}/{issue-number}-{kebab-case-title}

5. Transform Vault→GitHub

Map GTD task metadata to GitHub issue fields (status, priority, contexts → labels).

6. Transform GitHub→Vault

Map GitHub issue fields to GTD task metadata (labels → status, priority, contexts).

Confidence Thresholds:

90-100%: Auto-proceed
70-89%: Ask user to confirm
<70%: Present options, require selection

State Management

See: State Management Reference

Location: .claude/skills/github-issue-manager/state/{repo-name}/issue_state.json

State Schema: See State Template

Key Operations:

Initialize: Create new state for repository
Load: Resume from existing state
Update: Track new issues, tasks, syncs
Query: Find issues, tasks, check sync status

Tracked Data:

Issues created (number, type, labels, sync status)
Tasks created (path, title, sync source)
Sync relationships (issue ↔ task mappings)
Pending syncs (failed operations to retry)
Classification cache (learning from decisions)
Statistics (totals by type, sync counts)

GitHub MCP Integration

Required MCP Tools

Issue Operations:

mcp__github__issue_write - Create/update issues
mcp__github__issue_read - Read issue details
mcp__github__search_issues - Find related issues
mcp__github__add_issue_comment - Add comments

Repository Operations:

mcp__github__get_me - Get authenticated user
mcp__github__list_issues - List repository issues

MCP Usage Pattern

1. Check if GitHub MCP available
2. If available: Use MCP for GitHub operations
3. If not available: Provide manual instructions
4. Track in state: mcp_servers_used.push("github")

Vault Integration

See: Vault Sync Reference

Task Creation from Issues

Location: 05 Tasks/{issue-title}.md

Metadata Mapping: GitHub state/labels → vault status/priority/contexts/energy/timeEstimate

Body Mapping: Issue body + acceptance criteria + GitHub link

Issue Creation from Tasks

GitHub Fields: Task metadata → title/body/labels/milestone/state

Type Detection: Tags and title patterns → type-* labels

Bi-Directional Sync

After initial sync, maintain synchronization when either side changes. Conflict resolution available when both sides changed.

Label Conventions

Type (required): type-feature, type-bug, type-chore, type-enhancement Priority: priority-critical/high/medium/low Estimate: estimate-1h/2h/4h/8h/2d/1w Category: category-frontend/backend/database/api/docs/tests

See: Label Conventions Reference for complete guide

Reference Files

Core Concepts (9 files)

Location: references/core/

Foundation concepts and system design:

Issue Types - Detailed type descriptions and classification indicators
AI Decision Points - Decision logic, algorithms, confidence scoring
State Management - State operations, schema, queries
Vault Sync - Bi-directional sync logic and field mappings
Dependency Tracking - Issue dependencies and relationships
Issue Classification - Classification algorithms and rules
Label Conventions - Label standards and usage
Vault Sync Patterns - Sync patterns and strategies
Workflow Orchestration - Workflow coordination and execution

Workflows (4 files)

Location: references/workflows/

Detailed step-by-step workflow instructions:

Workflow 1: Create from Description - AI-powered issue creation
Workflow 2: Vault to GitHub - Task→Issue transformation
Workflow 3: GitHub to Vault - Issue→Task transformation
Workflow 4: Batch Creation - Planning doc→Issues

Templates (5 files)

Location: templates/

Reusable templates and configurations:

State Template - State file schema
Feature Issue - Feature template
Bug Issue - Bug template
Chore Issue - Chore template
Enhancement Issue - Enhancement template

Error Handling

GitHub MCP Not Available: Provides manual instructions, saves content to file Vault Task Creation Fails: Logs error, marks as pending sync, GitHub issue still created Classification Uncertainty (<70%): Asks user to confirm, shows reasoning Duplicate Detection: Searches similar titles, prompts user confirmation

See workflow reference files for detailed error handling procedures

Success Metrics

You've successfully used this skill when:

✅ Issues created with complete, structured information
✅ Proper labels applied automatically
✅ Dependencies identified and linked
✅ Vault tasks and GitHub issues stay in sync
✅ State file tracks all relationships
✅ Team can understand and act on issues immediately
✅ No manual copy-paste between vault and GitHub
✅ Classification confidence consistently high (>90%)
✅ Batch creation completes without errors
✅ Sync relationships maintained over time

Quick Examples

Example 1: Create Feature Issue

User: "Create a feature for implementing dark mode toggle"

Result:
✅ Issue #123 created
  Type: feature (90% confidence)
  Labels: type-feature, priority-medium, estimate-4h, category-frontend
  Vault task: 05 Tasks/Implement dark mode toggle.md
  Sync: ✅ Linked

Example 2: Sync Vault Task

User: "Sync this task to GitHub" [pointing to task file]

Result:
✅ Issue #124 created from vault task
  Task: Fix login error.md
  Type: bug (from tags)
  Labels: type-bug, priority-high, estimate-2h
  GitHub: https://github.com/owner/repo/issues/124

Example 3: Batch Create from Planning

User: "Create issues from development-stories.md"

Result:
✅ Batch creation complete!
  Created: 15 issues (#124-#138)
  Milestones: 3 phases
  Dependencies: 8 linked
  Vault tasks: 15 synced
  Time: 2 minutes

For detailed workflow examples, see individual workflow reference files.

Workflow Commands Summary

Create Issue

"Create a [feature|bug|chore|enhancement] issue for [description]"

Sync Vault Task

"Sync this task to GitHub"
"Create GitHub issue from [task name]"

Sync GitHub Issue

"Sync issue #123 to vault"
"Import issue #456 as a task"

Batch Create from Planning

"Create issues from my development stories"
"Create issues from [planning-doc.md]"

Classify Existing Issue

"Classify issue #456"
"Recommend labels for issue #789"

Integration with Spec-Planning

This skill is designed to work seamlessly with spec-planning skill:

spec-planning (Phase 5)
  ↓
development-stories.md created
  ↓
github-issue-manager (Workflow 4: Batch Creation)
  ↓
GitHub issues created with proper structure
  ↓
implementation skill
  ↓
Stories implemented one by one

Workflow: Planning → Issues → Implementation → Deployment

Best Practices

DO: Provide clear descriptions, review AI classifications, use consistent naming, sync early, track dependencies, validate previews

DON'T: Create duplicates, manually edit github_issue metadata, skip previews, ignore warnings, delete synced tasks without unlinking

Version History

v2.0.0 (2025-10-29):

Refactored to <500 lines with progressive disclosure
Organized 4 core concept files + 4 workflow files
Enhanced reference documentation structure
Improved clarity with summaries and links
Maintained all features from v1.0.0

v1.0.0 (2025-10-28):

Initial release with orchestrated workflow
AI-powered classification
Bi-directional vault sync
4 issue type templates
State management
Dependency tracking
GitHub MCP integration

Version: 2.0.0 Last Updated: 2025-10-29 Maintained by: Personal Workflow Workflow Mode: Orchestrated (ADW-inspired)

Install Skill

SKILL.md

GitHub Issue Manager Skill v2.0

Purpose

When to Use This Skill

Issue Types Supported

1. Feature (New Functionality)

2. Bug (Defect/Error)

3. Chore (Maintenance)

4. Enhancement (Improvement)

Orchestrated Workflows

Workflow 1: Create Issue from Description

Workflow 2: Sync Vault Task to GitHub

Workflow 3: Sync GitHub Issue to Vault

Workflow 4: Batch Issue Creation (from Planning Docs)

AI Decision Points

1. Classify Issue Type

2. Recommend Labels

3. Detect Dependencies

4. Generate Branch Name

5. Transform Vault→GitHub

6. Transform GitHub→Vault

State Management

GitHub MCP Integration

Required MCP Tools

MCP Usage Pattern

Vault Integration

Task Creation from Issues

Issue Creation from Tasks

Bi-Directional Sync

Label Conventions

Reference Files

Core Concepts (9 files)

Workflows (4 files)

Templates (5 files)

Error Handling

Success Metrics

Quick Examples

Example 1: Create Feature Issue

Example 2: Sync Vault Task

Example 3: Batch Create from Planning

Workflow Commands Summary

Create Issue

Sync Vault Task

Sync GitHub Issue

Batch Create from Planning

Classify Existing Issue

Integration with Spec-Planning

Best Practices

Version History