GitHub Project Board Skill

When to Activate

Use this skill when:

• Checking or reading a project board / backlog / sprint / kanban
• Finding work assigned to you or available to pick up
• Updating issue status on a board
• Adding progress comments to issues
• Creating issues or sub-issues on a board
• Handing off work between agents
• Any mention of "board", "backlog", "sprint", "kanban", "project board"

Agent Filtering (Optional)

Agents can be scoped to a subset of board issues using labels. This enables multiple independent agents to work the same board without stepping on each other.

• An agent given a label filter (e.g., --label research) only processes issues with that label
• An agent given no label filter processes any issue on the board (default behavior)
• Labels are assigned to issues, not board items — use gh issue edit to manage them
• Multiple labels can be combined: an issue labeled research,security is visible to both the "research" agent and the "security" agent

Label conventions

Use short, lowercase labels that describe the agent's domain or role:

Create labels in the repo if they don't exist:

gh label create <LABEL> --repo <OWNER>/<REPO> --description "<description>"

Assign a label to an issue:

gh issue edit <ISSUE_URL> --add-label "<LABEL>"

Board Requirements

This skill expects a board with three single-select fields — Status (In Definition, Todo, In progress, To Review, Ready, Done), Priority (Critical → Zero), and Size (XL → XS). To create a compatible board from scratch, see docs/board-setup.md.

Read-only and offline requests

Honor the requested scope: a backlog summary or proposed action does not authorize claims, comments, or status changes. For a supplied offline snapshot, analyze that input and label the result as a sample; do not claim live discovery occurred. Before an authorized live operation, use the discovery step below and re-read the current item before claiming it.

Board Discovery (Mandatory First Step)

Before any board operation, discover the board structure. All field IDs and option IDs are resolved dynamically — never hardcode them.

# 1. Get project metadata and README (workflow rules)
gh project view <NUMBER> --owner <OWNER> --format json

# 2. Get all fields with IDs and option values
gh project field-list <NUMBER> --owner <OWNER> --format json

# 3. Get all items with current field values
gh project item-list <NUMBER> --owner <OWNER> --format json --limit 100

From the field-list output, resolve:

• Status field ID — find the field where name == "Status"
• Status option IDs — map each option name ("Todo", "In progress", etc.) to its ID
• Priority field ID — find the field where name == "Priority"
• Priority option IDs — map each option name to its ID
• Size field ID — find the field where name == "Size"
• Project ID — from gh project view output, the id field (starts with PVT_)

Read the board README (gh project view ... --format json | jq -r .readme) to understand board-specific workflow rules. The README is authoritative for that board's conventions.

Board Workflow

The standard 6-status lifecycle:

In Definition → Todo → In Progress → To Review → Done
                                    → Ready → Done

Who controls what

Agents should never move items to "In Definition" or "Done" — those are human-controlled states.

Quick Command Reference

All commands use dynamically discovered IDs from the Board Discovery step.

List backlog items by status

# All Todo items (no label filter)
gh project item-list <NUMBER> --owner <OWNER> --format json --limit 100 \
  | jq '[.items[] | select(.status == "Todo")]'

List backlog items filtered by label

When an agent is scoped to a label, cross-reference the board items with the issue's labels. The item-list output includes each item's issue URL — use GraphQL to filter by label efficiently (see references/graphql-recipes.md recipe #6), or filter locally:

# Get Todo items, then check each for the target label
TODO_ITEMS=$(gh project item-list <NUMBER> --owner <OWNER> --format json --limit 100 \
  | jq '[.items[] | select(.status == "Todo")]')

# Filter by label (requires checking each issue)
echo "$TODO_ITEMS" | jq -r '.[].content.url' | while read url; do
  labels=$(gh issue view "$url" --json labels --jq '.labels[].name')
  if echo "$labels" | grep -q "^<LABEL>$"; then
    echo "$url"
  fi
done

Move item to a new status

gh project item-edit \
  --project-id <PROJECT_ID> \
  --id <ITEM_ID> \
  --field-id <STATUS_FIELD_ID> \
  --single-select-option-id <TARGET_STATUS_OPTION_ID>

Add a comment to an issue

gh issue comment <ISSUE_URL> --body "<structured comment>"

Create an issue and add to board

# Create the issue (add --label to assign to a specific agent)
gh issue create --repo <OWNER>/<REPO> --title "<title>" --body "<body>" \
  --label "<LABEL>"

# Add to board (use the returned issue URL)
gh project item-add <NUMBER> --owner <OWNER> --url <ISSUE_URL>

Set priority or size

gh project item-edit \
  --project-id <PROJECT_ID> \
  --id <ITEM_ID> \
  --field-id <PRIORITY_FIELD_ID> \
  --single-select-option-id <PRIORITY_OPTION_ID>

Create a sub-issue

gh issue create --repo <OWNER>/<REPO> \
  --title "<sub-issue title>" \
  --body "Parent: <PARENT_ISSUE_URL>"

# Then add to the board and set fields

Open board in browser

gh project view <NUMBER> --owner <OWNER> --web

Agent Comment Convention

When commenting on issues, use this structured format so other agents and humans can parse updates consistently:

## Agent Update — <AGENT_NAME>

**Status**: Working | Blocked | Complete | Needs Review
**Action**: <brief description of what was done>

### Details

<fuller description of the work, findings, or changes>

### Blockers (if any)

- <blocker description>

### Next Steps

- <next action to take>

---
_Updated by `<AGENT_NAME>` at <ISO 8601 timestamp>_

Agent Workflow Patterns

Pick Up Work

1. Discover the board (see Board Discovery above)
2. List items with status "Todo" — if a label filter was provided, only consider issues with that label
3. Sort by priority (Critical > Very High > High > Average > Low > Very Low > Zero)
4. Claim the highest-priority item by moving it to "In Progress"
5. Comment on the issue with an "Agent Update" noting you've started

Work Cycle

1. Read the issue description, comments, and attachments for requirements
2. Implement the requested work
3. Comment periodically with progress updates
4. Move to "To Review" (if you need feedback) or "Ready" (if work is complete)
5. Comment with a final summary of what was done

Ask for Clarification

1. Move the issue to "To Review"
2. Add a comment with your question using the Agent Comment Convention
3. Set **Status**: Blocked in the comment
4. A human will review, answer in comments, and move back to "Todo"
5. Pick it up again from the backlog

Submit for Approval

1. Move the issue to "Ready"
2. Add a comment with:
   • Summary of all changes made
   • Links to PRs or commits
   • Any caveats or known limitations
3. Set **Status**: Complete in the comment

Agent Handoff

1. Complete your portion of work
2. Add a structured comment summarizing what was done and what remains
3. Move the issue back to "Todo" (or keep in "In Progress" if the next agent should continue immediately)
4. The next agent picks it up following the "Pick Up Work" pattern

Quality Gate

Before marking any board operation as complete, verify:

• Status field was actually updated (re-read the item to confirm)
• Comment follows the Agent Comment Convention
• No stale "In Progress" items left behind (if you're done with an item, move it)
• Board README rules were followed

See references/ for the detailed command reference, GraphQL recipes, and expanded workflow patterns; examples/ for installation recipes, usage scenarios, and a full walkthrough; and docs/board-setup.md to create a compatible board.