design-to-issues
Converts approved design plan sections into trackable GitHub issue epics.
Install
mkdir -p .claude/skills/design-to-issues && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/12282" && unzip -o skill.zip -d .claude/skills/design-to-issues && rm skill.zipInstalls to .claude/skills/design-to-issues
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Creates a GitHub epic and child issues from a design document's implementation plan. Use when a design doc has a reviewed plan section ready to be converted into trackable work.Key capabilities
- →Read a design document to identify project name and plan section
- →Draft a GitHub epic issue body from the design document
- →Create a GitHub epic issue
- →Create child GitHub issues for non-deferred plan items
- →Update the epic issue with actual child issue numbers
How it works
The skill reads a design document, extracts the project plan, drafts an epic issue body, creates the epic, and then delegates to sub-agents to create child issues for each non-deferred plan item. Finally, it updates the epic with the created issue numbers.
Inputs & outputs
When to use design-to-issues
- →Turning design docs into issues
- →Managing project implementation tasks
- →Creating github epics
About this skill
Design Plan to GitHub Issues
Read a design document's implementation plan and produce a GitHub epic issue with linked child issues for each work item.
Prerequisites
- The design document must have a reviewed, approved plan section (typically a numbered task list organized into phases)
ghCLI authenticated- User has reviewed and approved the plan in the design doc before invoking this skill
Arguments
This skill accepts one argument: the path to the design document (e.g. docs/designs/theming.md).
Steps
1. Read the design document
Read the design doc at the provided path. Identify:
- The project name / title
- The plan section (typically the last major section, with numbered items organized into phases)
- Any items marked as deferred
2. Draft the epic
Compose the epic issue body. Format:
## Overview
<1-2 sentence summary of the project from the design doc's executive summary>
## Design document
<Relative path to the design doc in the repo, as a link>
## Plan
<Numbered checklist of all work items from the plan, including deferred items marked as such>
- [ ] #XX — <Item 1 title>
- [ ] #XX — <Item 2 title>
- [ ] [DEFERRED] <Item N title>
## Notes
- Deferred items are tracked here for completeness but do not have child issues yet.
- Check off items as their child issues are closed.
The #XX placeholders are filled in after child issues are created (step 4).
3. Create the epic issue
gh issue create --title "<Project name>: implementation epic" --body "<body>"
Save the epic issue number.
4. Create child issues
For each non-deferred plan item, delegate to a sub-agent using the gh-create skill. Use the Agent tool with model: "haiku" and subagent_type: "general-purpose".
Provide each sub-agent with:
- The parent epic issue number
- The item title
- A body prompt including: objective (from the plan item description), context (from the design doc), deliverable, and acceptance criteria
- Any dependency references (e.g. "depends on the token audit issue")
Run independent issue creations in parallel where possible (items without dependencies between them).
5. Update the epic
After all child issues are created, edit the epic body to replace #XX placeholders with actual issue numbers:
gh issue edit <epic-number> --body "<updated body with real issue numbers>"
6. Report
Show the user:
- The epic issue URL
- A summary table of all created child issues (number, title, dependencies)
- Which items were deferred and not issued
Notes
- This skill should run with Opus for the planning/orchestration. Child issue creation is delegated to Haiku via sub-agents.
- Research-oriented issues should note that their deliverable is "findings documented in issue comments + follow-up issues created or existing issues updated."
- Dependencies between issues should be mentioned in each issue's Context section, not enforced via GitHub's project tooling (keep it simple).
- Do not create issues for deferred items. They stay as unchecked lines in the epic until the user decides to promote them.
When not to use it
- →When the design document lacks a reviewed, approved plan section
- →When `gh` CLI is not authenticated
- →When the user has not reviewed and approved the plan in the design doc
Prerequisites
Limitations
- →Requires a reviewed and approved plan section in the design document.
- →Does not create issues for deferred items.
- →Dependencies between issues are mentioned in context, not enforced via GitHub's project tooling.
How it compares
This skill automates the conversion of a design document's implementation plan into a structured GitHub epic with linked child issues, ensuring design intent is translated into trackable work more efficiently than manual issue creation.
Compared to similar skills
design-to-issues side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| design-to-issues (this skill) | 0 | 5mo | No flags | Advanced |
| linear-ticket | 1 | 6mo | No flags | Intermediate |
| team-routing | 1 | 7mo | Review | Intermediate |
| team-workflow | 0 | 1mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
linear-ticket
useautumn
Refine rough engineering thoughts into structured Linear tickets with GitHub permalinks
team-routing
WellApp-ai
Detect domain from context and find appropriate team member
team-workflow
jevonsnotes
>
task-master
sfc-gh-dflippo
AI-powered task management for structured, specification-driven development. Use this skill when you need to manage complex projects with PRDs, break down tasks into subtasks, track dependencies, and maintain organized development workflows across features and branches.
agile-product-owner
davila7
Agile product ownership toolkit for Senior Product Owner including INVEST-compliant user story generation, sprint planning, backlog management, and velocity tracking. Use for story writing, sprint planning, stakeholder communication, and agile ceremonies.
writing-plans
obra
Use when you have a spec or requirements for a multi-step task, before touching code