board-manager

Manage GitHub Project board items - add issues, update status, move between columns. Use when user asks to add issues to board, change status, or organize the project.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The Board Manager skill enables Claude to programmatically manage GitHub Project boards (V2), streamlining software development lifecycles. By leveraging the GitHub CLI and GraphQL API, it automates the process of adding issues to boards, updating task statuses, and organizing columns. This skill is essential for maintaining an accurate, real-time overview of project progress directly within the developer workflow.

Use Cases

  • Automated Issue Onboarding: Automatically link newly created GitHub issues to a specific project board to ensure immediate visibility for the team.
  • Real-time Status Tracking: Update issue statuses to 'In Progress' or 'Blocked' as development work begins or encounters dependencies.
  • Seamless Workflow Transitions: Move tasks to 'Done' automatically after a pull request is merged, keeping the project board synchronized with the codebase.
  • Backlog Triage and Organization: Efficiently move triaged items from the backlog to 'Next' or other priority columns to facilitate sprint planning.
  • Project Board Maintenance: Use GraphQL mutations to precisely update custom single-select fields and maintain board hygiene without manual UI interaction.
nameboard-manager
descriptionManage GitHub Project board items - add issues, update status, move between columns. Use when user asks to add issues to board, change status, or organize the project.
allowed-toolsBash, Read

Board Manager Skill

Purpose

Add issues to the project board and update their status. This skill has write permissions for board operations.

When Claude Should Use This

  • User asks "add this issue to the board"
  • User asks "move #X to In Progress"
  • User asks "update status of issue"
  • User asks "put this in the backlog"
  • After creating a new issue (auto-add to board)
  • After completing work (move to Done)

Project Board Configuration

Project: Monorepo Development (#11) URL: https://github.com/orgs/rollercoaster-dev/projects/11

IDs Reference

Resource ID
Project ID PVT_kwDOB1lz3c4BI2yZ
Status Field ID PVTSSF_lADOB1lz3c4BI2yZzg5MUx4

Status Option IDs

Status Option ID Description
Backlog 8b7bb58f Not ready / needs triage
Next 266160c2 Ready to pick up
In Progress 3e320f16 Currently being worked on
Blocked 51c2af7b PR created, awaiting review
Done 56048761 Merged to main

Helper Functions

These reusable functions simplify board operations:

Get Item ID for Issue

get_item_id_for_issue() {
  local issue_number=$1
  gh api graphql -f query='
    query {
      organization(login: "rollercoaster-dev") {
        projectV2(number: 11) {
          items(first: 100) {
            nodes {
              id
              content { ... on Issue { number } }
            }
          }
        }
      }
    }' | jq -r ".data.organization.projectV2.items.nodes[] | select(.content.number == $issue_number) | .id"
}

Update Board Status (with validation)

update_board_status() {
  local item_id=$1
  local option_id=$2
  local status_name=$3

  RESULT=$(gh api graphql \
    -f projectId="PVT_kwDOB1lz3c4BI2yZ" \
    -f itemId="$item_id" \
    -f fieldId="PVTSSF_lADOB1lz3c4BI2yZzg5MUx4" \
    -f optionId="$option_id" \
    -f query='mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
      updateProjectV2ItemFieldValue(input: {
        projectId: $projectId
        itemId: $itemId
        fieldId: $fieldId
        value: { singleSelectOptionId: $optionId }
      }) {
        projectV2Item { id }
      }
    }' 2>&1)

  # Validate response - check for GraphQL errors
  if echo "$RESULT" | jq -e '.errors | length > 0' > /dev/null 2>&1; then
    echo "ERROR: Board update failed (GraphQL error)"
    return 1
  elif echo "$RESULT" | jq -e '.data.updateProjectV2ItemFieldValue.projectV2Item.id' > /dev/null 2>&1; then
    echo "Board Update: Issue moved to '$status_name'"
    return 0
  else
    echo "ERROR: Board update failed (unexpected response)"
    return 1
  fi
}

Commands

Add Issue to Project Board

gh project item-add 11 --owner rollercoaster-dev --url https://github.com/rollercoaster-dev/monorepo/issues/<number>

Get Item ID for an Issue

# Using GraphQL (more reliable - doesn't require read:org scope)
gh api graphql -f query='
  query {
    organization(login: "rollercoaster-dev") {
      projectV2(number: 11) {
        items(first: 100) {
          nodes {
            id
            content { ... on Issue { number } }
          }
        }
      }
    }
  }' | jq -r '.data.organization.projectV2.items.nodes[] | select(.content.number == <issue-number>) | .id'

Update Issue Status

# Use GraphQL mutation (avoids OAuth scope issues with gh project item-edit)
gh api graphql \
  -f projectId="PVT_kwDOB1lz3c4BI2yZ" \
  -f itemId="<item-id>" \
  -f fieldId="PVTSSF_lADOB1lz3c4BI2yZzg5MUx4" \
  -f optionId="<option-id>" \
  -f query='mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
    updateProjectV2ItemFieldValue(input: {
      projectId: $projectId
      itemId: $itemId
      fieldId: $fieldId
      value: { singleSelectOptionId: $optionId }
    }) {
      projectV2Item { id }
    }
  }'

Remove Issue from Project

gh project item-delete 11 --owner rollercoaster-dev --id <item-id>

Workflow Examples

Add New Issue and Set Status

# 1. Add to project using GraphQL mutation
ISSUE_NODE_ID=$(gh issue view 123 --json id -q .id)
gh api graphql -f query='
  mutation($projectId: ID!, $contentId: ID!) {
    addProjectV2ItemById(input: {
      projectId: $projectId
      contentId: $contentId
    }) { item { id } }
  }' -f projectId="PVT_kwDOB1lz3c4BI2yZ" -f contentId="$ISSUE_NODE_ID" 2>/dev/null || true

# 2. Get item ID and set status using helper functions
ITEM_ID=$(get_item_id_for_issue 123)
update_board_status "$ITEM_ID" "266160c2" "Next"

Move Issue to In Progress

# Using helper functions
ITEM_ID=$(get_item_id_for_issue <issue-number>)
update_board_status "$ITEM_ID" "3e320f16" "In Progress"

Move Issue to Blocked (after PR creation)

ITEM_ID=$(get_item_id_for_issue <issue-number>)
update_board_status "$ITEM_ID" "51c2af7b" "Blocked"

Move Issue to Done (after merge)

ITEM_ID=$(get_item_id_for_issue <issue-number>)
update_board_status "$ITEM_ID" "56048761" "Done"

Status Mapping

Action Status Option ID
New issue, not ready Backlog 8b7bb58f
Ready to work Next 266160c2
Started work In Progress 3e320f16
PR created Blocked 51c2af7b
PR merged Done 56048761

Output Format

After operations, confirm:

**Board Update:** Issue #X moved to [Status]
**URL:** https://github.com/orgs/rollercoaster-dev/projects/11

Query Current IDs (if they change)

gh api graphql -f query='
query {
  organization(login: "rollercoaster-dev") {
    projectV2(number: 11) {
      id
      field(name: "Status") {
        ... on ProjectV2SingleSelectField {
          id
          options { id name }
        }
      }
    }
  }
}'