GitHub Boards — drive your project board by conversation
Your coding agent can run your real GitHub Projects board. Tell it "put these on the board", "what's on my plate?", "undo what happened since this morning" — it previews every change, writes only with your OK, and reports back.
Demo as text
You: put these on the board: fix the login redirect bug (for Claude), renew the grant paperwork (for me)
Agent: Running it staged first — nothing is written yet:
Would file 2 card(s): 'Fix login redirect bug' → Ideas (agent); 'Renew grant paperwork' → Ideas (human). On your plate: 1 card(s). Claude's queue: 1 card(s).
Agent: Look right? (y/n)
You: y
✅ Filed 2 card(s). On your plate: 1 card(s). Claude's queue: 1 card(s).
You: what's on my plate?
✅ On your plate: 1 card(s). #8 Renew grant paperwork
Install
/plugin marketplace add deocracy/github-boards-skill
/plugin install github-boards@github-boards-skill
Already have gh authenticated and Node 18+? You're done — say "set up a board for this repo" and the skill walks you through the rest (or see Prerequisites).
Manual fallback (clone the full repo — the skill needs the bundled scripts):
The skill invokes scripts/board-manager.mjs and scripts/board.mjs; those scripts live at the repo root, not inside skills/github-boards/. Copying only skills/github-boards/ into ~/.claude/skills/ leaves the scripts behind and nothing runs. Keep the entire clone intact and register it as a local plugin:
# 1. Clone anywhere — keep the whole repo intact (scripts/ must stay alongside skills/):
git clone https://github.com/deocracy/github-boards-skill ~/github-boards-skill
# 2. Register the clone as a local marketplace and install from it:
claude plugin marketplace add ~/github-boards-skill
claude plugin install github-boards@github-boards-skill
# The plugin install keeps scripts/ and skills/ together at the repo root,
# so the skill's script references resolve correctly.
# Do NOT copy just skills/github-boards/ — that strips the scripts.
What you can say
| You say… | What happens |
|---|
| "Put these three tasks on the board" | Files real Issues onto the board (put) — after a staged preview you approve |
| "What's on my plate?" / "What is Claude working on?" | Your 🧍 queue vs the 🤖 agent queue (queue human / queue agent) |
| "Move the API card to Review" / "This one needs me" | Lane moves (move) and owner re-routing (route) |
| "Reject this, keep the learnings" | Terminal lane + a recorded note (reject) |
| "Sync my TODOs onto the board" | Watched files → extraction → ledger (sync scan / sync record) — nothing touches the board yet |
| "Figure out what belongs on the board" / "Promote the backlog" | The mapper proposes cards (map), then promote files them — idempotent and resume-safe |
| "What changed this week?" / "Is the board out of sync?" | summary diffs since last look; reconcile heals ledger drift (never the board) |
| "What did the board look like before the cleanup?" / "Undo what happened since X" | snapshot history, diffs, and a computed undo plan (snapshot invert) you approve op by op |
Power-user extras: followup (file child cards), reshape (lane presets), bootstrap (provision a board from the current repo), ledger (the pipeline's inbox), and --staged on any write to preview without committing. Full verb reference: wiki Usage.
Why it's safe to point at your real board
- Every write is previewed first. The skill runs verbs staged, shows you the exact cards/lanes/labels, and commits only on your explicit OK. Never a silent write to the board.
- Fail-closed. Missing config, ambiguous board, inaccessible project → it stops and says so. It never guesses.
- Owner-routing is explicit. 🤖
agent:go vs 🧍 needs-claude labels say who should act — your queue stays real, and human-routed cards escalate with a mention instead of silently parking.
- History with an undo. Every session snapshots the board; a permanent journal records what changed; "undo since X" computes the exact inverse plan and replays it through the same approval-gated verbs.
- Your credentials stay yours. It drives the
gh CLI you already authenticated — no tokens in config files.
The pipeline (for batch work)
