ralph-json-create-issues
Converts a PRD or plan markdown file into prd.json format for ralph-json-start-loop to execute autonomously. Use when user wants to convert a PRD or plan to JSON stories.
How do I install this agent skill?
npx skills add https://github.com/richtabor/agent-skills --skill ralph-json-create-issuesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a utility for converting markdown project requirements into structured JSON files. It operates locally and does not perform network actions or execute code. The only identified concern is the potential for instructions inside the markdown files to influence the conversion process.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
Create PRD JSON
Convert a Product Requirements Document or plan file into JSON for Ralph.
Input
Check these locations in order:
.claude/plans/— Where plan mode saves approved plans. Primary source.plans/— Project-level plans directory.prds/— Standalone PRDs not generated from plan mode.
If files exist in multiple locations, list all and ask which to convert. If only one file is found, use it directly. If no files are found in any location, ask the user for the path to their PRD/plan file.
Conversion Rules
Story Sizing (Critical)
Each story MUST complete in ONE Ralph iteration (one context window).
Right-sized:
- Add a database column
- Create a single UI component
- Add one API endpoint
- Add form validation
- Update a server action
Too large (must split):
❌ "Build entire auth system"
✅ "Add login form"
✅ "Add email validation"
✅ "Add auth server action"
Dependency Ordering
Stories execute sequentially by priority:
- Database/schema changes
- Backend logic
- API endpoints
- UI components
Cross-PRD Dependencies (Critical)
Ralph respects dependsOn to sequence PRDs. Before generating JSON:
- Scan existing PRDs — Read all
prds/*.jsonto know what features exist - Detect dependencies — Look for references in the markdown PRD:
- Explicit: "See
elevenlabs-integration.md", "Depends on morning brief" - Implicit: Story notes mentioning other features
- Technical: Uses tables/APIs defined in another PRD
- Explicit: "See
- Populate
dependsOn— Array of PRD names (without.jsonextension)
Examples of dependency detection:
# In evening-ritual.md:
"See `elevenlabs-integration.md` for shared infrastructure"
→ dependsOn: ["elevenlabs-integration"]
"Depends on morning brief feature for regeneration"
→ dependsOn: ["elevenlabs-integration", "morning-brief"]
If no dependencies detected:
"dependsOn": []
Acceptance Criteria (Critical)
Must be explicit and verifiable:
Good:
- Email/password fields present
- Validates email format
- Shows error on invalid input
- Typecheck passes
- Verify at localhost:3000/login
Bad:
- Users can log in (vague)
- Works correctly (vague)
- Good UX (subjective)
Required in every story:
- "Typecheck passes"
- "Lint passes"
Required for UI stories:
- "Verify at localhost:3000/[path]"
Output Format
Generate prds/[feature-name].json:
{
"projectName": "Feature Name",
"branchName": "ralph/feature-name",
"description": "Brief description",
"dependsOn": ["other-feature", "another-feature"],
"status": "pending",
"completedAt": null,
"userStories": [
{
"id": "US-001",
"title": "Add login form",
"description": "As a user, I want to see a login form so I can authenticate",
"acceptanceCriteria": [
"Email/password fields present",
"Form submits on enter",
"Typecheck passes",
"Lint passes",
"Verify at localhost:3000/login"
],
"priority": 1,
"passes": false,
"notes": ""
}
]
}
Process
- Scan existing PRDs — Read
prds/*.jsonto understand the dependency landscape - Read the PRD/plan markdown file from
.claude/plans/,plans/, orprds/ - Derive feature name from filename (e.g.,
auth-flow.md→auth-flow) - Detect dependencies — Check for references to other PRDs in the markdown
- Break into right-sized stories starting at US-001
- Order by dependency (set priority)
- Add explicit acceptance criteria
- Save to
prds/[feature-name].json
Pre-Save Checklist
Before saving, verify:
- Each story completable in one iteration
- Stories ordered by dependency
- All criteria include "Typecheck passes"
- UI stories include "Verify at localhost:3000/..."
- No vague criteria ("works", "good", "correct")
- Story IDs are sequential (US-001, US-002, ...)
-
dependsOnis populated (empty array if no dependencies) - Dependencies reference existing PRD names (without extension)
After Conversion
Created prds/[feature-name].json with [N] stories
Dependencies: [list or "none"]
Branch: ralph/[feature-name]
Run: /ralph-json-start-loop
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/richtabor/agent-skills/ralph-json-create-issues">View ralph-json-create-issues on skillZs</a>