Analyze Issue
Turn a GitHub issue number into a structured technical specification your agent can implement against.
Overview
analyze-issue is an agent skill for the Build phase that analyzes a GitHub issue and writes a detailed technical specification under your specs workflow.
Install
npx skills add https://github.com/neolabhq/context-engineering-kit --skill analyze-issueWhat is this skill?
- Accepts issue number argument and loads or fetches GitHub issue content into ./specs/issues/ with padded numeric kebab-c
- Produces full technical specification: summary, problem, approach, numbered implementation plan, and layered test plan
- Enumerates files to modify and files to create for the implementing agent
- Uses gh CLI via Bash(gh issue:*) plus Read, Write, Glob, and Grep for repo context
- Integrates with context-engineering-kit load-issues conventions when the issue file is not already local
- Spec sections: Issue Summary, Problem Statement, Technical Approach, Implementation Plan, Test Plan (unit/component/inte
- Issue file naming: number padded to 3 digits plus kebab-case title under ./specs/issues/
Adoption & trust: 525 installs on skills.sh; 1.1k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a GitHub issue full of product language but no ordered technical plan, test matrix, or file list for your coding agent to follow.
Who is it for?
Indie developers using gh issues and the context-engineering-kit specs folder who want agent-generated engineering specs before writing code.
Skip if: Repositories without GitHub Issues, teams that forbid gh CLI, or work that only needs a one-line hotfix with no written spec.
When should I use this skill?
You have a GitHub issue number and need a detailed technical specification with implementation and test plans aligned to your specs/issues layout.
What do I get? / Deliverables
You get a structured technical specification for the issue—including implementation steps and test plan—saved in your specs/issues workflow, ready to hand off to implementation skills.
- Technical Specification for Issue #N markdown with implementation and test plans
- Optional cached issue markdown under ./specs/issues/
Recommended Skills
Journey fit
Issue-to-spec work sits in Build PM: translating backlog items into actionable engineering plans before coding. PM subphase covers specs, breakdown, and files-to-touch lists derived from tracker issues—not runtime monitoring or marketing.
How it compares
Issue-to-spec planner for agent implementation—not a PR reviewer or automatic merge bot.
Common Questions / FAQ
Who is analyze-issue for?
Solo builders and tiny teams on GitHub who store issue context under ./specs/issues/ and want Claude or Cursor to draft implementation-ready specs from an issue number.
When should I use analyze-issue?
During Build PM when an issue is approved for work but lacks engineering detail—right after loading issues and before you invoke coding or testing skills.
Is analyze-issue safe to install?
It runs gh issue commands and writes spec files; check Prism Security Audits and restrict Bash/gh access to repos you trust with read/issue fetch and local spec writes.
SKILL.md
READMESKILL.md - Analyze Issue
Please analyze GitHub issue #$ARGUMENTS and create a technical specification. Follow these steps: 1. Check if the issue is already loaded: - Look for the issue file in `./specs/issues/` folder - File naming pattern: `<number-padded-to-3-digits>-<kebab-case-title>.md` - If not found, fetch the issue details from GitHub (see step 2) 2. Fetch the issue details (if not already loaded): - Read `.claude/commands/load-issues.md` to understand how to fetch issue details - Save the issue file following the load-issues.md format 3. Understand the requirements thoroughly 4. Review related code and project structure 5. Create a technical specification with the format below # Technical Specification for Issue #$ARGUMENTS ## Issue Summary - Title: [Issue title from GitHub] - Description: [Brief description from issue] - Labels: [Labels from issue] - Priority: [High/Medium/Low based on issue content] ## Problem Statement [1-2 paragraphs explaining the problem] ## Technical Approach [Detailed technical approach] ## Implementation Plan 1. [Step 1] 2. [Step 2] 3. [Step 3] ## Test Plan 1. Unit Tests: - [test scenario] 2. Component Tests: - [test scenario] 3. Integration Tests: - [test scenario] ## Files to Modify - [file path]: [changes] ## Files to Create - [file path]: [purpose] ## Existing Utilities to Leverage - [utility name/path]: [purpose] ## Success Criteria - [ ] [criterion 1] - [ ] [criterion 2] ## Out of Scope - [item 1] - [item 2] Remember to follow our strict TDD principles, KISS approach, and 300-line file limit. IMPORTANT: After completing your analysis, SAVE the full technical specification to: `./specs/issues/<number-padded-to-3-digits>-<kebab-case-title>.specs.md` For example, for issue #7 with title "Make code review trigger on any *.SQL and .sh file changes", save to: `./specs/issues/007-make-code-review-trigger-on-sql-sh-changes.specs.md` After saving, provide a brief summary to the user confirming: - Issue number and title analyzed - File path where the specification was saved - Key highlights from the specification (2-3 bullet points)