Skip to content
AI-SKILLS

Ralph PRD Converter

👤 Snarktank
•
📅 January 27, 2026
•
⭐ 8.6K
View on GitHub →

Introduction

Ralph PRD Converter is a specialized utility for the Ralph autonomous agent ecosystem. It solves the critical challenge of translating high-level Product Requirements Documents (PRDs) into a machine-readable prd.json format that an autonomous agent can execute reliably.

The primary hurdle for autonomous agents is the context window. Large, vague tasks often lead to broken code and hallucination. This skill ensures that every requirement is:

  • Atomized: Broken down into single-iteration tasks.
  • Ordered: Sequenced by technical dependency (e.g., Database > Backend > UI).
  • Verifiable: Equipped with concrete acceptance criteria that the agent can check via terminal or browser.

Installation

To integrate the Ralph PRD Converter into your Claude Code environment, ensure you have the Ralph repository cloned and configured.

  1. Clone the repository: git clone https://github.com/snarktank/ralph

  2. Navigate to your project directory where Ralph is initialized.

  3. Ensure your SKILL.md or system prompt includes the Ralph conversion logic to recognize the following triggers:

    • convert this prd
    • turn this into ralph format
    • create prd.json from this

Usage

Once active, you can provide any Markdown or text-based PRD to Claude and request a conversion.

Example Prompt

“I have an existing PRD for a new user notification system. Convert this into Ralph format and create the prd.json file.”

Core Conversion Rules

To ensure the autonomous loop succeeds, the skill enforces several strict formatting rules:

  • The One-Iteration Rule: Each user story must be completable in a single context window. If a change cannot be described in 2-3 sentences, the skill automatically splits it into smaller stories.
  • Dependency Sequencing: Logic follows a strict hierarchy:
    1. Schema/Database changes and migrations.
    2. Server Actions and backend logic.
    3. UI Components utilizing the backend.
    4. Aggregated Views (Dashboards/Summaries).
  • Verifiable Criteria: Every story includes mandatory checks such as Typecheck passes. Frontend stories automatically include Verify in browser using dev-browser skill.

Output Structure

The skill generates a structured prd.json located in your ralph/ directory:

{
  "project": "ProjectName",
  "branchName": "ralph/feature-name",
  "description": "Feature summary",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add database column",
      "description": "As a user...",
      "acceptanceCriteria": ["Migration runs", "Typecheck passes"],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Best Practices

Note: Before saving a new prd.json, the skill checks for existing files. If a prd.json exists for a different branch and contains progress, it will prompt to archive the previous run into archive/YYYY-MM-DD-feature-name/ to prevent data loss.

  • Be Specific: When providing the raw PRD, include specific field names or UI elements to help the skill generate better acceptance criteria.
  • Verify Logic: Always review the generated priority sequence to ensure the database migrations are scheduled before the UI components.
  • Automated Verification: Ensure your environment has the dev-browser skill enabled, as the PRD converter will frequently reference it for visual verification of frontend tasks.