# Github Project Board

> GitHub Project Board CLI Skill

- Skill: `elodhorvath/github-project-board` (Agent Skill)
- Install (CLI): `npx skillmds@latest add elodhorvath/github-project-board`
- Raw SKILL.md: https://api.skillmd.com/api/skills/elodhorvath/github-project-board/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: elodhorvath (https://skillmd.com/u/elodhorvath)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/elodhorvath/github-project-board

---

# GitHub Project Board CLI Skill

Use the GitHub CLI (`gh`) to manage issues and pull requests on a GitHub Projects (V2) board.

## Prerequisites

- `gh` CLI installed and authenticated.
- `project` OAuth scope is required for project operations. If project commands fail with permission errors, run:

  ```bash
  gh auth refresh -s project
  ```

## Common Commands

### Find a project

```bash
gh project list --owner <owner>
```

Use the numeric project number (e.g., `1`) for most commands.

### Add an issue or PR to a project

```bash
gh project item-add <project-number> --owner <owner> --url <issue-or-pr-url>
```

Example:

```bash
gh project item-add 1 --owner elodhorvath --url https://github.com/elodhorvath/LMS-Extract/pull/180
```

### List project items

```bash
gh project item-list <project-number> --owner <owner> --format json
```

**Note:** Newly added items may not appear in the default result set. Use `--limit 100` to ensure recent items are returned.

```bash
gh project item-list 1 --owner elodhorvath --format json --limit 100
```

The JSON shape is:

```json
{
  "items": [
    {
      "id": "PVTI_lAHOA6991M4BCx0uzgwDmkM",
      "content": {
        "type": "PullRequest",
        "url": "https://github.com/...",
        "title": "..."
      }
    }
  ]
}
```

### Find an item ID by URL

```bash
gh project item-list <project-number> --owner <owner> --format json --limit 100 | \
  jq -r '.items[] | select(.content.url == "<issue-or-pr-url>") | .id'
```

### List project fields

```bash
gh project field-list <project-number> --owner <owner> --format json
```

The JSON shape is:

```json
{
  "fields": [
    {
      "id": "PVTSSF_lAHOA6991M4BCx0uzg04_u8",
      "name": "Status",
      "type": "ProjectV2SingleSelectField",
      "options": [
        { "id": "f75ad846", "name": "Backlog" },
        { "id": "e18bf179", "name": "Ready" },
        { "id": "47fc9ee4", "name": "In progress" },
        { "id": "aba860b9", "name": "In review" },
        { "id": "98236657", "name": "Done" }
      ]
    }
  ]
}
```

### Update an item's status

Use the field ID and option ID, **not** the human-readable names.

```bash
gh project item-edit \
  --project-id <project-id> \
  --id <item-id> \
  --field-id <status-field-id> \
  --single-select-option-id <status-option-id>
```

Example:

```bash
gh project item-edit \
  --project-id PVT_kwHOA6991M4BCx0u \
  --id PVTI_lAHOA6991M4BCx0uzgwDmkM \
  --field-id PVTSSF_lAHOA6991M4BCx0uzg04_u8 \
  --single-select-option-id aba860b9
```

## ID Reference

| Object | Prefix | Example |
|--------|--------|---------|
| Project | `PVT_kw` | `PVT_kwHOA6991M4BCx0u` |
| Project item | `PVTI_l` | `PVTI_lAHOA6991M4BCx0uzgwDmkM` |
| Single-select field | `PVTSSF_l` | `PVTSSF_lAHOA6991M4BCx0uzg04_u8` |
| Plain field | `PVTF_l` | `PVTF_lAHOA6991M4BCx0uzg04_u0` |

## Troubleshooting

- **Permission denied / not authorized:** Run `gh auth refresh -s project`.
- **Item not found after add:** Re-run `item-list` with `--limit 100`.
- **`unknown flag: --field`:** Use `--field-id` and `--single-select-option-id` instead.
- **`Cannot index array with string "name"`:** `field-list` returns `{ fields: [...] }`; index `.fields[]`.
- **`Cannot index array with string "content"`:** `item-list` returns `{ items: [...] }`; index `.items[]`.