Instructions

You are acting as an autonomous sub-agent to parse a Product Requirements Document (PRD) and scaffold a GitHub milestone by creating GitHub Issues for each user story.

PREREQUISITE: The GitHub CLI (gh) MUST be installed and fully authenticated (gh auth login) for this skill to function.

Workflow

1. Setup Labels: Before creating any issues, verify the user-story label exists and that a label for the specific feature prefix (e.g., PRI) exists. Run gh label list --limit 1000 | grep "user-story". If not found, create it: gh label create "user-story" --color "0e8a16" --description "User story task". Repeat this check and creation process for the PRD's specific prefix if applicable: gh label create "<prefix>" --color "1d76db".

2. Parse PRD: Read the specified PRD file (e.g., docs/PRD.md or tasks/prd-[feature].md). Extract all User Stories and their complete details, including Titles, Descriptions, Acceptance Criteria, Technical Notes, Data Models, dependencies, the feature prefix representing this PRD, and any other relevant context.

3. Identify Dependencies: If the PRD outlines dependencies between user stories, note them. You will add these as comments or task lists in the issues.

4. Idempotency Check: Before creating an issue, check if an issue already exists for a given user story using gh issue list --search "in:title <User Story Title>". This prevents creating duplicate issues if the skill is run multiple times.

5. Create Issues: Loop through the extracted stories. For each uncreated story, construct a GitHub blob URL to the PRD file. Get the repo info with gh repo view --json nameWithOwner -q (format: owner/repo), then format the issue body:

   ## Description
   <User Story Description>
   
   ## Acceptance Criteria
   - [ ] <Criterion 1>
   - [ ] <Criterion 2>
   ...
   
   ## Technical Notes
   <Any technical details>
   
   ## Original PRD
   [View in PRD](https://github.com/<owner>/<repo>/blob/main/<prd-file-path>)
   

   Example: https://github.com/eho/test-example/blob/main/tasks/prd-example.md

   Run the bundled script to create the issue safely. Capture its output to extract the issue number for dependency linking in Step 6. Script location: The script is at SKILL_DIR/scripts/create_issue.sh, where SKILL_DIR is the directory containing this SKILL.md file. Resolve it using the base directory provided at the top of the skill invocation (look for "Base directory for this skill:"). If not available, locate it at <git repo root>/.agents/skills/prd-to-github-milestone/scripts/create_issue.sh.

   # Use a temporary file for the body to keep the command clean and avoid shell escaping issues
   SKILL_DIR="<base directory from skill invocation>"
   cat <<'EOF' > issue_body.md
   ## Description
   ...
   EOF
   
   OUTPUT=$("$SKILL_DIR/scripts/create_issue.sh" "<Story ID>: <Title>" "user-story,<prefix>" issue_body.md)
   ISSUE_NUMBER=$(echo "$OUTPUT" | grep "Issue Number:" | awk '{print $3}')
   rm issue_body.md
   

   If there are dependencies noted from Step 3, add them to the issue body as a "Dependencies" section, or add a comment later once all issues are created.

6. Link Dependencies: After creating all issues, if there are dependencies between user stories, add comments to dependent issues listing their blockers. Use the captured issue numbers from Step 5:

   gh issue comment <dependent-issue-number> --body "Depends on: #<blocker-issue-number>"
   

   For example: gh issue comment 43 --body "Depends on: #42"

7. Create & Link to Milestone:

   • Determine the milestone name: Check if the PRD explicitly organizes stories by milestone. If yes, use that name. Otherwise, use the PRD feature name.
   • Create the milestone first (ensures it exists): "$SKILL_DIR/scripts/create_milestone.sh" "<Milestone Title>" (where SKILL_DIR is the base directory from the skill invocation; if not available, locate it at <git repo root>/.agents/skills/prd-to-github-milestone/scripts/create_milestone.sh).
   • Link all created issues to the milestone: gh issue edit <issue-number> --milestone "<Milestone Title>".

8. Output Mapping: Generate a markdown table and present to user:

   | Story ID | Title | Issue # | URL |
   |----------|-------|---------|-----|
   | PRI-001 | User Login | #12 | https://github.com/.../issues/12 |
   | PRI-002 | User Logout | #13 | https://github.com/.../issues/13 |
   

Available Scripts

This skill bundles the following scripts in the scripts/ subdirectory relative to this SKILL.md file:

• create_issue.sh "<title>" "<labels>" "<body_file_path>": Safely executes gh issue create and extracts the issue number.
• create_milestone.sh "<milestone_title>": Safely executes gh api to create a new milestone.

Examples

Example 1: Input: "Create issues from tasks/prd-login.md and add them to the 'v1.0' milestone" Action:

1. Setup labels: gh label list --limit 1000 | grep "user-story". If not found, run gh label create "user-story" --color "0e8a16". Extract the prefix (PRI from tasks/prd-login.md), then check and create it: gh label create "PRI" --color "1d76db".
2. Read tasks/prd-login.md.
3. Extract PRI-001 (Login), PRI-002 (Logout) with dependencies: PRI-002 depends on PRI-001.
4. Get repo info: gh repo view --json nameWithOwner -q → returns myorg/myapp.
5. Create issue for PRI-001:

   cat <<'EOF' > issue_body.md
   ## Description
   User should be able to log in...
   
   ## Acceptance Criteria
   - [ ] Form validates email
   - [ ] Form validates password
   
   ## Original PRD
   [View in PRD](https://github.com/myorg/myapp/blob/main/tasks/prd-login.md)
   EOF
   
   OUTPUT=$("$SKILL_DIR/scripts/create_issue.sh" "PRI-001: User Login" "user-story,PRI" issue_body.md)
   # Extract the ISSUE_NUMBER output by the script for dependency linking
   ISSUE_NUMBER=$(echo "$OUTPUT" | grep "Issue Number:" | awk '{print $3}')
   rm issue_body.md
   

6. Create issue for PRI-002 (with dependency noted):

   cat <<'EOF' > issue_body.md
   ## Description
   User should be able to log out...
   
   ## Dependencies
   - Depends on #42 (User Login)
   
   ## Original PRD
   [View in PRD](https://github.com/myorg/myapp/blob/main/tasks/prd-login.md)
   EOF
   
   "$SKILL_DIR/scripts/create_issue.sh" "PRI-002: User Logout" "user-story,PRI" issue_body.md
   rm issue_body.md
   

7. Create milestone v1.0 and link both issues.
8. Output summary:

   | Story ID | Title | Issue # | URL |
   |----------|-------|---------|-----|
   | PRI-001 | User Login | #42 | https://github.com/myorg/myapp/issues/42 |
   | PRI-002 | User Logout | #43 | https://github.com/myorg/myapp/issues/43 |