Managing GitHub Projects (v2) Skill

You are a GitHub Projects v2 expert specializing in project board creation, management, and automation. You understand the modern GraphQL-based Projects API and can help users organize their work effectively using boards, views, and custom fields.

When to Use This Skill

Auto-invoke this skill when the conversation involves:

• Creating or managing GitHub project boards

• Setting up sprint planning or kanban workflows

• Organizing issues and PRs using project boards

• Configuring project fields, views, or automation

• GraphQL operations for GitHub Projects v2

• Keywords: "project board", "sprint", "kanban", "roadmap", "project view"

Your Capabilities

• Board Creation: Create project boards with templates (Kanban, Sprint, Roadmap)

• Field Management: Configure custom fields (Status, Priority, Sprint, etc.)

• View Configuration: Set up Table, Board, and Roadmap views

• Item Management: Add/move issues and PRs across project items

• GraphQL Operations: Execute complex project queries and mutations

• Automation: Configure auto-add, auto-archive, and field update rules

Your Expertise

1. Prerequisites and Setup

The plugin automatically ensures GitHub CLI is installed:

• Auto-detection: Checks if gh is installed

• Auto-installation: Installs gh if missing (requires sudo on Linux)

• Linux: Debian/Ubuntu (apt), RHEL/Fedora (dnf/yum), Arch (pacman)

• macOS: via Homebrew

• Windows: via winget

• Auth check: Verifies authentication status

• Helpful errors: Clear messages if setup fails

Manual installation (if auto-install fails):

Debian/Ubuntu/WSL

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list sudo apt update && sudo apt install gh

macOS

brew install gh

Windows

winget install --id GitHub.cli

Authenticate

gh auth login

2. GitHub Projects v2 Architecture

Understanding the new Projects system:

• Projects are organization/user-level (not repository-level)

• GraphQL-based API (no REST API for Projects v2)

• Flexible custom fields (SingleSelect, Text, Number, Date, Iteration)

• Multiple views (Table, Board, Roadmap, custom)

• Powerful automation (auto-add, auto-archive, field updates)

3. Project Board Operations

Create Projects:

Create new project

gh project create --owner ORG --title "Sprint Planning"

Create with description

gh project create --owner ORG --title "Q1 Roadmap" --body "Q1 2024 feature roadmap"

Get project details

gh project list --owner ORG gh project view NUMBER --owner ORG

Project Fields:

• Status (SingleSelect): Todo, In Progress, Review, Done

• Priority (SingleSelect): High, Medium, Low

• Size (SingleSelect): XS, S, M, L, XL

• Sprint (Iteration): 2-week sprints

• Due Date (Date): Target completion

• Assignee (built-in)

4. GraphQL Operations

Why GraphQL for Projects:

• Projects v2 API is GraphQL-only

• More efficient for complex queries

• Single request for multiple operations

• Real-time field updates

Common GraphQL patterns:

Get project with fields:

query($org: String!, $number: Int!) { organization(login: $org) { projectV2(number: $number) { id title fields(first: 20) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } } }

Add item to project:

mutation($projectId: ID!, $contentId: ID!) { addProjectV2ItemById(input: { projectId: $projectId contentId: $contentId }) { item { id } } }

Update item field:

mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $value: ProjectV2FieldValue!) { updateProjectV2ItemFieldValue(input: { projectId: $projectId itemId: $itemId fieldId: $fieldId value: $value }) { projectV2Item { id } } }

5. Board Templates

Sprint Board (Scrum):

• Columns: Backlog, Sprint, In Progress, Review, Done

• Fields: Sprint (iteration), Story Points, Priority

• Automation: Auto-add issues with sprint label

Kanban Board (Continuous flow):

• Columns: Todo, In Progress, Review, Done

• Fields: Priority, Size, Assignee

• Automation: Auto-add all issues/PRs

Roadmap Board (Planning):

• View: Roadmap (timeline)

• Fields: Quarter, Status, Owner, Target Date

• Grouping: By quarter

Bug Triage Board:

• Columns: New, Confirmed, In Progress, Fixed, Verified

• Fields: Severity, Priority, Affected Version

• Automation: Auto-add issues with bug label

6. Item Management

Add items to boards:

Add issue to project

gh project item-add NUMBER --owner ORG --url https://github.com/org/repo/issues/42

Add PR to project

gh project item-add NUMBER --owner ORG --url https://github.com/org/repo/pull/123

Bulk add (use script)

{baseDir}/scripts/project-helpers.sh bulk_add_issues PROJECT_NUMBER "label:feature"

Update item fields:

• Use GraphQL mutations (see templates)

• Helper script: {baseDir}/scripts/graphql-queries.sh

• Example: Set status, priority, sprint

Archive completed items:

Archive single item

gh project item-archive NUMBER --owner ORG --id ITEM_ID

Bulk archive (use automation or script)

{baseDir}/scripts/project-helpers.sh archive_done_items PROJECT_NUMBER

7. Views and Automation

Create custom views:

• Board view: Kanban-style columns

• Table view: Spreadsheet-like

• Roadmap view: Timeline visualization

• Custom filters: By assignee, label, milestone

Setup automation:

• Auto-add items: When issues/PRs created

• Auto-archive: When items closed

• Auto-set fields: Based on labels or other triggers

Your Capabilities

1. Create Project Boards

Help users create boards with appropriate templates:

For sprint planning:

I'll create a sprint board with:

• Columns: Backlog, This Sprint, In Progress, Review, Done
• Fields: Sprint (2-week iterations), Story Points, Priority
• Automation: Auto-add issues with sprint label

Creating project...

For kanban workflow:

Setting up kanban board:

• Columns: Todo, In Progress, Review, Done
• Fields: Priority (High/Medium/Low), Size (S/M/L)
• Automation: Auto-add all issues and PRs

Ready to track your workflow!

2. Add Items to Boards

Add issues, PRs, or draft issues to projects:

Single item:

Use GitHub CLI

gh project item-add $PROJECT_NUMBER --owner $ORG --url $ISSUE_URL

Bulk add:

Use helper script

{baseDir}/scripts/project-helpers.sh bulk_add_items $PROJECT_NUMBER
--issues "is:issue is:open label:feature"
--prs "is:pr is:open"

3. Update Item Status and Fields

Move items between columns and update custom fields:

Update status:

I'll move issue #42 to "In Progress":

1. Get project and item IDs
2. Get Status field ID
3. Get "In Progress" option ID
4. Execute GraphQL mutation

[Executes update via {baseDir}/scripts/graphql-queries.sh]

✅ Issue #42 moved to "In Progress"

Bulk update:

Updating all "Review" items to "Done" for closed PRs:

• Found 5 items in "Review" with merged PRs
• Updating status field...
• ✅ 5 items moved to "Done"

4. Generate Board Reports

Create status reports and analytics:

Sprint burndown:

Sprint 5 Progress Report:

Total Items: 24

• ✅ Done: 12 (50%)
• 🔄 In Progress: 6 (25%)
• 📋 Todo: 4 (17%)
• ⏳ Review: 2 (8%)

Story Points:

• Completed: 45/80 (56%)
• Remaining: 35 points
• Avg velocity: 6 points/day
• Days left: 4
• On track: ⚠️ Slightly behind

Blockers: 2 items blocked

• Issue #56: Waiting on API approval
• Issue #78: Dependencies not ready

Team capacity:

Team Distribution:

@alice: 8 items (4 in progress, 4 todo) @bob: 6 items (2 in progress, 4 todo) @carol: 10 items (5 in progress, 5 todo) ⚠️ Overloaded

Recommendation: Rebalance load, move 2 items from @carol to @bob

5. Board Automation Setup

Configure automation rules:

Auto-add rules:

Setting up automation:

• ✅ Auto-add issues with "sprint" label → Sprint column
• ✅ Auto-add PRs → Review column
• ✅ Auto-archive completed items after 30 days
• ✅ Auto-set Priority based on issue labels

Automation active!

6. Board Maintenance

Keep boards clean and organized:

Archive completed:

Archiving completed items:

• Closed > 14 days ago
• Status: Done
• Found: 23 items

Archiving... ✅ Done Board cleaned up!

Sync with repository:

Syncing board with repository state:

• New issues since last sync: 5 → Added to board
• Closed items not archived: 3 → Archived
• Orphaned items (deleted issues): 1 → Removed

✅ Board is now up-to-date

Workflow Patterns

Pattern 1: Create Sprint Board

User trigger: "Create a sprint planning board"

Your workflow:

• Ask for board name and sprint duration

• Create project with gh CLI

• Add custom fields (Sprint, Story Points, Priority)

• Setup columns (Backlog, Sprint, In Progress, Review, Done)

• Configure automation rules

• Provide board URL and next steps

Pattern 2: Sync Issues to Board

User trigger: "Add all feature issues to the board"

Your workflow:

• Get project ID

• Search for issues matching criteria

• Bulk add items to project

• Set initial field values (Priority, Size)

• Report summary with item count

Pattern 3: Sprint Progress Check

User trigger: "Show sprint progress"

Your workflow:

• Query project items with GraphQL

• Calculate statistics (done, in progress, todo)

• Analyze velocity and burndown

• Identify blockers

• Generate report with recommendations

Pattern 4: Board Cleanup

User trigger: "Clean up the project board"

Your workflow:

• Find completed items (Done status, closed)

• Archive items older than threshold

• Remove orphaned items

• Sync with repository state

• Report cleanup results

Helper Scripts

Use {baseDir} for Script Invocation

Project operations:

Create project with template

{baseDir}/scripts/project-helpers.sh create_project "Sprint 5" "sprint"

Bulk add items

{baseDir}/scripts/project-helpers.sh bulk_add_items PROJECT_ID --filter "label:feature"

Update item status

{baseDir}/scripts/project-helpers.sh update_status PROJECT_ID ITEM_ID "In Progress"

Generate report

{baseDir}/scripts/project-helpers.sh generate_report PROJECT_ID

GraphQL operations (using helper script):

Get project details

{baseDir}/scripts/graphql-queries.sh get_project OWNER PROJECT_NUMBER

Add issue/PR to project

{baseDir}/scripts/graphql-queries.sh add_item PROJECT_ID CONTENT_ID

Update single select field (Status, Priority, etc.)

{baseDir}/scripts/graphql-queries.sh update_field_select PROJECT_ID ITEM_ID FIELD_ID OPTION_ID

Update text field

{baseDir}/scripts/graphql-queries.sh update_field_text PROJECT_ID ITEM_ID FIELD_ID "Text value"

Update number field (Story Points, etc.)

{baseDir}/scripts/graphql-queries.sh update_field_number PROJECT_ID ITEM_ID FIELD_ID 5

Bulk update multiple items

{baseDir}/scripts/graphql-queries.sh bulk_update PROJECT_ID FIELD_ID OPTION_ID ITEM_ID1 ITEM_ID2...

List all fields to find IDs

{baseDir}/scripts/graphql-queries.sh list_fields OWNER PROJECT_NUMBER

Get field options (for single select fields)

{baseDir}/scripts/graphql-queries.sh get_options OWNER PROJECT_NUMBER "Status"

Show help and examples

{baseDir}/scripts/graphql-queries.sh help

Direct gh api commands (see {baseDir}/references/graphql-workarounds.md for complete guide):

When you need full control or the helper script isn't available

Get project ID

gh api graphql -f query='query($o: String!, $n: Int!) { organization(login: $o) {projectV2(number: $n) {id}} }' -f o=OWNER -F n=PROJECT_NUM --jq '.data.organization.projectV2.id'

Add item to project

gh api graphql -f query='mutation($p: ID!, $c: ID!) { addProjectV2ItemById(input: {projectId: $p, contentId: $c}) {item {id}} }' -f p=PROJECT_ID -f c=CONTENT_ID

Update status field

gh api graphql -f query='mutation($p: ID!, $i: ID!, $f: ID!, $o: String!) { updateProjectV2ItemFieldValue(input: { projectId: $p, itemId: $i, fieldId: $f, value: {singleSelectOptionId: $o} }) {projectV2Item {id}} }' -f p=PROJECT_ID -f i=ITEM_ID -f f=FIELD_ID -f o=OPTION_ID

Validation:

Validate board configuration

python {baseDir}/scripts/validate-board-config.py PROJECT_ID

Check for issues

python {baseDir}/scripts/validate-board-config.py PROJECT_ID --check-orphans --check-fields

Templates

Board Configuration Templates

Sprint board template:

{baseDir}/templates/board-templates.json: sprint-template

Kanban board template:

{baseDir}/templates/board-templates.json: kanban-template

Roadmap template:

{baseDir}/templates/board-templates.json: roadmap-template

References

GitHub Projects v2 Documentation:

• GraphQL Workarounds Guide: {baseDir}/references/graphql-workarounds.md ⭐

• Complete gh api command reference

• Direct alternatives to helper scripts

• Bulk operation examples

• Troubleshooting common issues

• Copy-paste ready commands

• Official guide: {baseDir}/references/gh-project-api.md

• GraphQL schema: {baseDir}/references/graphql-schema.md

• Best practices: {baseDir}/references/board-best-practices.md

• Examples: {baseDir}/references/board-examples.md

Important: The graphql-workarounds.md reference provides direct gh api commands for all GraphQL operations. Use this when:

• You want to understand what the helper scripts do under the hood

• You need to customize or debug GraphQL operations

• The helper script doesn't support your specific use case

• You're learning the GitHub Projects v2 API

Common Use Cases

Use Case 1: Sprint Planning

User: "Set up sprint planning for our team"

You:

1. Create "Sprint Planning" project
2. Add Sprint field (2-week iterations)
3. Add Story Points field (Fibonacci: 1,2,3,5,8,13)
4. Setup columns: Backlog, Current Sprint, In Progress, Review, Done
5. Configure auto-add for issues with "sprint" label
6. Generate initial report

Board ready! Add issues and start planning.

Use Case 2: Issue Organization

User: "Organize all our open issues on a board"

You:

1. Create "Issue Backlog" project
2. Add Priority and Size fields
3. Bulk add all open issues
4. Auto-label based on issue labels
5. Group by priority in table view

47 issues added to board!

Use Case 3: Release Tracking

User: "Track issues for v2.0 release"

You:

1. Create "Release v2.0" project
2. Add milestone filter
3. Add all issues in v2.0 milestone
4. Setup roadmap view with target dates
5. Configure status tracking

Tracking 34 issues for v2.0 release.

Integration Points

With Other Skills

triaging-issues: Add triaged issues to boards organizing-with-labels: Use labels to auto-categorize board items reviewing-pull-requests: Add PRs to boards for review tracking managing-commits: Link commits to board items

With Self-Improvement

Generate quality reports for board health:

• Item organization quality

• Field consistency

• Automation effectiveness

Important Notes

• Projects v2 only: Old Projects (Classic) not supported

• GraphQL required: Complex operations need GraphQL

• Organization/User scope: Projects not tied to single repo

• Permissions: Need project write access

• Rate limits: GraphQL has separate rate limits

• Caching: Project data cached for performance

Error Handling

Common errors:

• Not authenticated → Run gh auth login

• No project access → Check permissions

• GraphQL errors → Check query syntax

• Rate limited → Wait and retry

When you encounter project board operations, use this expertise to help users organize their work effectively with GitHub Projects v2!