issues-workflow_skill

Overview

This skill implements an Issues-first GitHub workflow that treats Issues as the single source of truth for content, hierarchy, status, and history. It leverages native sub-issues for structured work and uses GitHub Projects v2 only as an optional visualization layer for cross-repo dashboards or stakeholder reports. The skill provides commands, conventions, and automation patterns to create, link, and track issues consistently across repos.

How this skill works

The skill creates and manages parent issues and native sub-issues, applies label-based status and classification, and offers scripts to auto-link issues into Projects v2 when visualization is required. It uses the GitHub CLI and API patterns: gh issue create/edit/list for issue management and gh project item-add or GraphQL for project status updates. Token guidance and label-to-project mapping conventions are included to keep Projects read-only for content.

When to use it

• Setting up hierarchical work using native sub-issues (epics, research breakdowns, phased releases)
• Tracking status and history without relying on Project custom fields
• Creating cross-repo dashboards or Kanban views with Projects v2 as visualization only
• Configuring auto-linking from Issues to Projects using label conventions or a config file
• Running research workflows where findings, analysis, and conclusions must be preserved in issue history

Best practices

• Keep all content (analysis, findings, decisions) inside issue bodies and comments — Projects v2 must not store content
• Use sub-issues for structured or multi-step work; use markdown checklists for tiny, transient lists
• Adopt label patterns (status:*, priority:*, research:*, type:*) for filters and automation
• Reserve Projects v2 for visualization and stakeholder reports; avoid storing editable content there
• Use Classic PAT tokens for Projects API operations; use fine-grained tokens for standard issue operations if Projects aren’t needed

Example use cases

• Epic decomposition: create a parent issue for an epic and sub-issues for individual features, track completion via progress bar
• Research workflow: parent issue holds hypothesis and sub-issues cover experiments; label outcomes research:validated or research:invalidated
• Cross-repo roadmap: keep content in repo issues and add links to a Projects v2 dashboard for stakeholders
• Auto-linking: bulk-add validated research issues to a central project using label-to-project mappings and gh project item-add