Guide · Agent skill
How to use the Gap Analysis to GitHub Issues agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gen-specs-as-issues skill is a set of instructions that turns an AI coding agent into a product manager for a software project. It reads the project's docs, code and tests, finds features the documentation promises but the code does not fully deliver, scores them, and writes specification drafts formatted as GitHub issues. It is useful for maintainers, sprint planners and developers new to a codebase. By the end of this guide you will know how to install the skill, how to ask for a review, and what the output will and will not do.
Gap Analysis to GitHub Issuesgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Get the gen-specs-as-issues ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ for one project.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill there instead.
- 4Open the project. Start your agent from inside the repository so it can read the README, docs, code and tests.
- 5Ask for a gap review. Request a review of missing features and ask for issue drafts for the top three.
- 6Check the scores. Read the 1-5 scores and the priority reasoning, since they are the agent's judgement.
- 7Edit and post the drafts. Refine the issue drafts and create them in GitHub yourself, as the file includes no issue-creation tooling.
What the skill makes the agent do
The skill is a single file, SKILL.md, that describes a six-phase workflow. The agent first learns the project by reading the README, other documentation, the main entry points, core modules and tests. It then compares what the documentation says the project can do against what is actually implemented, and looks for placeholder code and broken or missing user steps.
Next, the agent lists 5 to 7 potential missing features and scores each one on a 1-5 scale for user impact, strategic alignment, implementation feasibility, resource requirements and risk level. It presents the top three and writes a specification for each, covering overview and scope, technical requirements, implementation plan and acceptance criteria. Finally, it drafts each as a GitHub issue with dependency notes and an effort estimate.
- Reads README, docs, code and tests
- Flags placeholder or incomplete features
- Scores gaps and picks the top three
- Writes specs and issue drafts with acceptance criteria and dependency notes
Install the skill from the ZIP or the Claude apps
Download the ZIP for this skill from the page, then choose one of two routes. For a personal setup, unzip it into ~/.claude/skills/ so the skill is available across your projects. For a single project, unzip it into that project's .claude/skills/ folder so it is only available there.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills. Confirm that the folder containing SKILL.md ends up where the skill loader expects it; if the skill does not appear, check the folder structure first.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language to review the project for gaps, and mention the outcome you want. The skill's description covers identifying missing features, prioritising them and creating specifications, so requests that match that wording tend to load it. Run the request from inside the project so the agent can read the files.
Good requests name the project and the output. The skill assumes the agent can read the repository, so make sure you open the right folder first.
- "Review this repo for missing features and draft GitHub issues for the top three."
- "Compare the README against the implementation and tell me what is still placeholder code."
- "Give me a gap overview of this codebase I am new to."
- "Write issue drafts with acceptance criteria for the next sprint from the gaps you find."
Examples of what you get back
A typical run produces a ranked list of gaps, then three full specifications. Each specification includes a scope section that states what is explicitly excluded, a list of files to create or modify, and acceptance criteria that name the tests that should pass. Each issue draft follows a fixed template with Overview, Scope, Technical Requirements, Implementation Plan, Acceptance Criteria, Priority, Dependencies and Implementation Size sections.
The skill also asks for a final review that summarises the specifications, highlights dependencies and suggests an implementation order. Treat the output as a draft to edit, not a finished backlog.
- Top three gaps with status, impact and dependencies
- Per-feature spec with scope, technical needs, plan and acceptance criteria
- Issue drafts with blocks / blocked-by notes and effort estimates
- A suggested implementation order
What you need before you start
The agent must be able to read the project files, because the whole workflow depends on reading code and documentation. GitHub access is only needed if you want issues actually created. The file itself does not set up any tooling for creating issues, so you should expect drafts that you then post yourself or through your own setup.
The skill does not run scripts and does not use the network, according to the file. Its behaviour is set entirely by the text of SKILL.md.
- Read access to the project repository
- GitHub access only if you want issues created automatically (not provided by this file)
Safety notes on scripts and network
The skill file contains no scripts and makes no network calls. The main risk is reading the wrong material: the agent works from whatever files it can see, so point it at the intended repository and avoid giving it access to unrelated private folders.
Scores are judgement calls made by the agent. The formula uses 1-5 ratings that may vary between runs, so check the reasoning before you act on the ranking.
- No scripts are run by this skill
- No network use is specified
- Review the scoring rationale before committing to a priority order
Tips for better results
Keep the scope narrow. Asking the agent to focus on one module or entry point gives more useful gaps than asking about a whole large project. Ask it to show the evidence for each gap, such as the README line and the file that is a placeholder, so you can verify it.
Use the output for planning, not for final decisions. The skill favours simple MVP work and asks the agent to consider open-source contributors, which suits maintainers and onboarding, but you still decide what enters the sprint.
- Limit the review to one area of the codebase
- Ask for file and documentation references for each gap
- Edit the issue drafts before publishing them
What people use it for
- Maintainers of an open-source project reviewing what is still missing before a release planning meeting.
- Product-minded developers preparing draft issues with acceptance criteria for the next sprint.
- New contributors onboarding to an unfamiliar codebase who want a structured overview of gaps and placeholders.
Frequently asked questions
How do I install the gen-specs-as-issues skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, go to Settings → Capabilities → Skills and upload it there.
What does the gen-specs-as-issues skill require?
The agent must be able to read the project files, since the workflow depends on code and documentation. GitHub access is only needed if you want issues created, and the file does not include tooling for that.
Is the gen-specs-as-issues skill free?
The skill is listed under the MIT licence on this page. Check the licence file in the source repository for the full terms before reuse.
Does the skill create GitHub issues automatically?
No. The SKILL.md describes issue creation and provides issue templates, but it does not include any script or tool setup for creating issues. You will need to post the drafts yourself or set up your own tooling.
Does the skill run scripts or use the internet?
According to the file, it runs no scripts and uses no network. Its behaviour comes entirely from the instructions in SKILL.md.
How is this different from just asking an AI to find bugs?
This skill follows a fixed workflow: it compares documented capabilities against the implementation, scores each gap on five criteria, picks the top three and writes full specs with acceptance criteria. A general request may not follow that structure or produce the same issue template.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you maintain a project or plan sprints and want a structured, documented review of what is still missing, with draft issues you can edit. Pick something else if the agent cannot read your repository, or if you need the scores to be objective or issues created automatically without your own tooling.
Download the skill