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
/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.| 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.
- 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:govs 🧍needs-claudelabels 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
ghCLI you already authenticated — no tokens in config files.
TODO.md / plans / other skills' artifacts
└─ sync ─► intent ledger ─► map (LLM proposes, code validates) ─► promote ─► board
maintenance: reconcile (ledger healing) · snapshots (memory + undo)
Direct verbs act immediately; the pipeline batches work through a ledger so nothing files twice and every promotion resumes after a crash. Hooks keep you oriented: a board digest at session start, a one-line note when a watched file changes.
The skill's instruction body is vendor-neutral and mirrored to AGENTS.md — agents that read the AGENTS.md convention (Codex, Cursor, and friends) get the same contract. All board logic lives in the bundled scripts, not in any vendor's prompt format.
Any skill can record work onto the board — "use the github-boards skill to put these tasks on the board" — and gets the same staged-preview contract plus a report-back to relay. Contract: docs/COMPOSABILITY.md.
- Claude Code — the runtime.
- GitHub CLI (
gh), authenticated: rungh auth loginonce. The skill uses your stored credentials — you never paste a token into a config file. - A GitHub token with
projectandreposcopes (a classic PAT, or a fine-grained PAT with Projects: read & write and Issues: read & write).gh auth logincan grant these. (repois required because the skill files real GitHub Issues.) - Node.js 18+ on your PATH. (Claude Code does not bundle Node; the engine is a Node script.)
- A GitHub Project (v2) board — see One-time board setup below.
GitHub does not let any token create or group a board view — that's browser-only. So once per board, you (a human) do this in the GitHub UI:
- Create a Project (v2).
- Add a single-select field named
Stagewith your lane options (e.g. Ideas, Researching, Building, Review, Shipped, Rejected (learnings kept) — or your own; see Configuration). - Set the board view to group by
Stage.
The skill's doctor command prints this checklist and tells you exactly what's missing. After that, the skill handles everything data-shaped (filing cards, moving lanes, routing, commenting).
Actively maintained and fully tested (the whole pipeline runs under a deterministic simulation harness — crash recovery, multi-session lifecycles, a seeded soak). One live-hardening pass against a real board remains before 1.0 — see the runbook and ROADMAP.
MIT — see LICENSE.