Write A Prd
Turn a fuzzy feature idea into a scoped PRD filed as a GitHub issue before your agent starts coding.
Overview
write-a-prd is an agent skill most often used in Validate (also Build) that interviews you, explores the repo, and files a scoped PRD as a GitHub issue.
Install
npx skills add https://github.com/mattpocock/ralph-workshop-repo-001 --skill write-a-prdWhat is this skill?
- Seven-step interview flow from problem narrative through repo verification to module sketching
- Deep-module guidance: simple testable interfaces that encapsulate churning internals
- Explicit in-scope / out-of-scope negotiation before writing the doc
- PRD output follows a structured template submitted as a GitHub issue
- Optional step skipping when repo context already answers open questions
- 7-step PRD workflow from problem interview through module sketch
Adoption & trust: 5 installs on skills.sh; 16 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a feature idea but no repo-verified problem statement, scope fence, or modular plan your agent can execute against.
Who is it for?
Solo builders shipping features in an existing repo who want PRDs tied to real code layout and explicit non-goals.
Skip if: One-line tweaks or chores where a GitHub issue would be overhead and scope is already frozen in an approved SPEC.
When should I use this skill?
Use this skill when writing a PRD for a feature.
What do I get? / Deliverables
You get a GitHub-issue PRD with problem, scope, modules, and test intent so implementation skills can start from an approved artifact.
- GitHub issue PRD from the embedded template
- Agreed in-scope and out-of-scope implementation list
- Major module sketch with optional test targets
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
PRDs lock problem, scope, and module boundaries after validation and before implementation—canonical shelf is validate/scope. The skill explicitly hammers in-scope vs out-of-scope and deep modules, which is classic feature scoping work.
Where it fits
Turn a landing-page experiment into a PRD with explicit non-goals before touching production code.
Compare solution options after repo exploration so the PRD reflects what already exists in the stack.
Break an epic into deep modules and test expectations as GitHub issues the build loop can pick up.
How it compares
Use instead of dumping requirements into chat without repo exploration or a published scope document.
Common Questions / FAQ
Who is write-a-prd for?
Indie and solo developers using Claude Code or similar agents who want GitHub-native PRDs before coding a feature.
When should I use write-a-prd?
During Validate when scoping a feature, during Build when splitting a large initiative into issues, or anytime you need a deep-module map grounded in the current codebase.
Is write-a-prd safe to install?
It guides interviews and issue creation; review the Security Audits panel on this page before granting repo write or GitHub API access to your agent.
SKILL.md
READMESKILL.md - Write A Prd
This skill will be invoked when the user wants to create a PRD. You should go through the steps below. You may skip steps if you don't consider them necessary. 1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions. 2. Explore the repo to verify their assertions and understand the current state of the codebase. 3. Ask whether they have considered other options, and present other options to them. 4. Interview the user about the implementation. Be extremely detailed and thorough. 5. Hammer out the exact scope of the implementation. Work out what you plan to build and what you DON'T plan to build as part of this PRD. 6. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. 7. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. The PRD should be submitted as a GitHub issue. <prd-template> ## Problem Statement The problem that the user is facing, from the user's perspective. ## Solution The solution to the problem, from the user's perspective. ## User Stories A LONG, numbered list of user stories. Each user story should be in the format of: 1. As an <actor>, I want a <feature>, so that <benefit> <user-story-example> 1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending </user-story-example> This list of user stories should be extremely extensive and cover all aspects of the feature. ## 'Polishing' Requirements Once the user stories are complete, we will end up with a working, but not refined, feature or application. After the work is complete, we should enter a polishing phase. This should be a list of checks that we want to make at the end of the work to polish and refine the work done for maximum user enjoyment and experience. They should not meaningfully extend the work but instead ensure harmony of all created elements and ensure any errors are properly handled and make things delightful and beautiful. ## Implementation Decisions A list of implementation decisions that were made. This can include: - The modules that will be built/modified - The interfaces of those modules that will be modified - Technical clarifications from the developer - Architectural decisions - Schema changes - API contracts - Specific interactions Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. ## Testing Decisions A list of testing decisions that were made. Include: - A description of what makes a good test (only test external behavior, not implementation details) - Which modules will be tested - Prior art for the tests (i.e. similar types of tests in the codebase) ## Out of Scope A description of the things that are out of scope for this PRD. ## Further Notes Any further notes about the feature. </prd-template>