migrate-board

Migrate a markdown Kanban board to GitHub Issues and Projects v2.

Updated Apr 21, 2026
One-click install
npx skills add https://github.com/Zeyad-37/tech-agency --skill migrate-board-zeyad-37
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: migrate-board
Source: https://github.com/Zeyad-37/tech-agency/tree/main/.claude/skills/migrate-board
Command: npx skills add https://github.com/Zeyad-37/tech-agency --skill migrate-board-zeyad-37

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams tracking work in markdown files (board-context.md and docs/board/) eventually hit scaling limits: no search, no notifications, no PR integration. This Skill moves the entire board to GitHub Issues with an optional Projects v2 board, without losing history or creating duplicates. ## Core Features & Use Cases - Safe, resumable migration: Every issue creation is preceded by an exact title-prefix lookup, so an interrupted run is resumed by simply re-running the Skill — never by manual cleanup. - Board repair before migration: The bundled parser validates table structure, detects merge corruption (split tables, wrong headers, duplicate Task IDs), and reports each problem with a concrete fix before anything is written. - Tech-debt import: Optionally migrates the tech-debt backlog, merging items onto existing board tasks with severity labels or creating standalone labeled issues. - History preservation: Nothing is deleted — markdown files are frozen with a banner, and Done rows can either become closed issues or stay as frozen markdown history. - Use Case: A team whose board-context.md has grown to hundreds of tasks says "migrate board to GitHub Issues"; the Skill dry-runs the parse, creates labels and issues, links epic sub-issues, verifies both directions, then flips board_backend to github. ## Quick Start Ask the AI to migrate the markdown board to GitHub Issues by saying "migrate board" from the root of a repo that has board-context.md and a GitHub remote.

Frequently Asked Questions about migrate-board

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate a markdown Kanban board to GitHub Issues?▼

Run the migrate-board skill from the repo root with the gh CLI authenticated. It validates and repairs the markdown tables, dry-runs the parse for confirmation, creates labels and issues with exact title-prefix deduplication, links epic sub-issues, verifies both directions, then freezes the markdown files.

Is it safe to re-run a GitHub Issues migration after it fails halfway?▼

Yes. Every issue creation is preceded by a lookup matching the exact [TASK-ID] title prefix client-side, so already-created issues are skipped. A run interrupted by rate limits or errors is resumed by re-running the same step, never by manual cleanup.

Does the migration delete the original markdown board files?▼

No. The markdown files stay in the repo, frozen with a banner pointing to GitHub Issues. Done rows can either become closed issues or remain as frozen markdown history, depending on the chosen Done mode.

What happens if my markdown board has corrupted tables?▼

The parse_board.py validator detects corruption classes such as separator rows without headers, tables split by blank lines, wrong column schemas, duplicate Task IDs, and unescaped pipes. Each problem is reported with a concrete repair, which should be committed separately before migrating.

Can I migrate without the GitHub Projects v2 scope?▼

Yes. If the token lacks the project scope, the migration runs label-only and skips the Projects v2 board creation. Running gh auth refresh -s project later and re-running the skill will create the board view.

How are tech-debt backlog items handled during migration?▼

Active debt items either merge onto an existing board task's issue with tech-debt and severity labels, or become their own Backlog issues. Resolved debt tables are never migrated since an issue represents open work.