Agent skill

Prd Converter

by YougLin-dev in YougLin-dev/Aha-Loop

Converts PRDs to prd.json format for Aha Loop autonomous execution.

MITAuto-check passedProduct & Project Management

Install Prd Converter

skills CLI
$ npx skills add YougLin-dev/Aha-Loop --skill prd-converter -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install YougLin-dev/Aha-Loop prd-converter --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/YougLin-dev/Aha-Loop.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/prd-converter .claude/skills/prd-converter && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
prd-converter
GitHub stars
181
Token cost
~2.6k tokens
SKILL.md length
831 words
Files
1
Skills in repo
15
Repo updated
First seen
Licence
MIT

At a glance

Converts PRDs to prd.json format for Aha Loop autonomous execution.

  • Works in 4 steps: Schema/database changes (migrations) → Server actions / backend logic → UI components that use the backend → …
  • Converting existing PRDs to JSON format
  • SKILL.md covers The Job, Output Format (v2), Story Size: The Number One Rule and Story Ordering: Dependencies…, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Prd Converter is an agent skill from YougLin-dev/Aha-Loop. Converts PRDs to prd.json format for Aha Loop autonomous execution. Use when converting existing PRDs to JSON format. Triggers on: convert prd, create prd.json, aha-loop format.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Product & Project Management, covering PRD writing. The repository describes itself as: [MVP] Aha Loop is a fully autonomous AI development system, extended from the core ideas of Ralph. It's not just an execution engine, but a complete AI development framework with… The licence is MIT.

When your agent uses it

  • Converting existing PRDs to JSON format
  • Create prd.json
  • Aha-loop format

Example prompts

  • “Use the prd-converter skill to convert PRDs to prd.json format for Aha Loop autonomous execution”
  • “/prd-converter”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Schema/database changes (migrations)
  2. Server actions / backend logic
  3. UI components that use the backend
  4. Dashboard/summary views that aggregate data

What it can do on your machine

Read from SKILL.md and the folder at commit 8d799b2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are json and markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Prd Converter loads about 2.6k tokens when it runs. Until then it costs about 48 tokens; SKILL.md has 831 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~48
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from YougLin-dev/Aha-Loop at commit 8d799b2, republished under its MIT licence (© YougLin-dev). 831 words, ~2,609 tokens.

Download SKILL.mdSave it as .claude/skills/prd-converter/SKILL.md (or your agent's skills folder).
name
prd-converter
description
Converts PRDs to prd.json format for Aha Loop autonomous execution. Use when converting existing PRDs to JSON format. Triggers on: convert prd, create prd.json, aha-loop format.

Aha Loop PRD Converter

Converts existing PRDs to the prd.json format that Aha Loop uses for autonomous execution.


The Job

Take a PRD (markdown file or text) and convert it to prd.json in the scripts/aha-loop directory.


Output Format (v2)

json
{
  "version": 2,
  "prdId": "[PRD-XXX from roadmap or PRD filename]",
  "project": "[Project Name]",
  "branchName": "aha-loop/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "changeLog": [],
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "researchTopics": [
        "Question about technology or best practice",
        "Question about existing patterns"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    }
  ]
}
New v2 Fields Explained
FieldPurpose
versionSchema version (always 2)
prdIdPRD identifier (e.g., PRD-001) for commit message prefixes
changeLogArray of plan modifications made during execution
researchTopicsQuestions to investigate before implementing the story
researchCompletedWhether research phase is done for this story
learningsKnowledge gained during implementation (filled by Aha Loop)
implementationNotesGuidance from research phase for implementation

Story Size: The Number One Rule

Each story must be completable in ONE Aha Loop iteration (one context window).

Aha Loop spawns a fresh AI instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.

Right-sized stories:
  • Add a database column and migration
  • Add a UI component to an existing page
  • Update a server action with new logic
  • Add a filter dropdown to a list
Too big (split these):
  • "Build the entire dashboard" - Split into: schema, queries, UI components, filters
  • "Add authentication" - Split into: schema, middleware, login UI, session handling
  • "Refactor the API" - Split into one story per endpoint or pattern

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.


Story Ordering: Dependencies First

Stories execute in priority order. Earlier stories must not depend on later ones.

Correct order:

  1. Schema/database changes (migrations)
  2. Server actions / backend logic
  3. UI components that use the backend
  4. Dashboard/summary views that aggregate data

Wrong order:

  1. UI component (depends on schema that does not exist yet)
  2. Schema change

Acceptance Criteria: Must Be Verifiable

Each criterion must be something the execution engine can CHECK, not something vague.

Good criteria (verifiable):
  • "Add status column to tasks table with default 'pending'"
  • "Filter dropdown has options: All, Active, Completed"
  • "Clicking delete shows confirmation dialog"
  • "Typecheck passes"
  • "Tests pass"
Bad criteria (vague):
  • "Works correctly"
  • "User can do X easily"
  • "Good UX"
  • "Handles edge cases"
Always include as final criterion:
"Typecheck passes"

For stories with testable logic, also include:

"Tests pass"
For stories that change UI, also include:
"Verify in browser using dev-browser skill"

Frontend stories are NOT complete until visually verified. Aha Loop will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.


Conversion Rules

  1. Version: Always set "version": 2
  2. prdId: Set from roadmap PRD ID (e.g., PRD-001) or derive from PRD filename
  3. Each user story becomes one JSON entry
  4. IDs: Sequential (US-001, US-002, etc.)
  5. Priority: Based on dependency order, then document order
  6. All stories: passes: false, researchCompleted: false, empty notes, learnings, implementationNotes
  7. branchName: Derive from feature name, kebab-case, prefixed with aha-loop/
  8. Always add: "Typecheck passes" to every story's acceptance criteria
  9. researchTopics: Extract from PRD's Research Topics section, or generate if story involves:
    • Unfamiliar third-party libraries
    • Multiple implementation approaches
    • Performance-sensitive code
    • Complex integrations
  10. changeLog: Initialize as empty array []

Show full SKILL.md (327 more words)Show less

Splitting Large PRDs

If a PRD has big features, split them:

Original:

"Add user notification system"

Split into:

  1. US-001: Add notifications table to database
  2. US-002: Create notification service for sending notifications
  3. US-003: Add notification bell icon to header
  4. US-004: Create notification dropdown panel
  5. US-005: Add mark-as-read functionality
  6. US-006: Add notification preferences page

Each is one focused change that can be completed and verified independently.


Example

Input PRD:

markdown
# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

Output prd.json (v2):

json
{
  "version": 2,
  "prdId": "PRD-001",
  "project": "TaskApp",
  "branchName": "aha-loop/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "changeLog": [],
  "userStories": [
    {
      "id": "US-001",
      "title": "Add status field to tasks table",
      "description": "As a developer, I need to store task status in the database.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "researchTopics": [
        "Best practices for enum columns in this database",
        "Migration rollback strategies"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored status badge",
        "Badge colors: gray=pending, blue=in_progress, green=done",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "researchTopics": [
        "Existing badge components in codebase",
        "Accessible color schemes for status indicators"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list.",
      "acceptanceCriteria": [
        "Each row has status dropdown or toggle",
        "Changing status saves immediately",
        "UI updates without page refresh",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "researchTopics": [],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "researchTopics": [
        "URL state management patterns in this codebase"
      ],
      "researchCompleted": false,
      "learnings": "",
      "implementationNotes": "",
      "notes": ""
    }
  ]
}

Archiving Previous Runs

Before writing a new prd.json, check if there is an existing one from a different feature:

  1. Read the current prd.json if it exists
  2. Check if branchName differs from the new feature's branch name
  3. If different AND progress.txt has content beyond the header:
    • Create archive folder: archive/YYYY-MM-DD-feature-name/
    • Copy current prd.json and progress.txt to archive
    • Reset progress.txt with fresh header

The aha-loop.sh script handles this automatically when you run it, but if you are manually updating prd.json between runs, archive first.


Checklist Before Saving

Before writing prd.json, verify:

  • Version set to 2
  • prdId set (from roadmap or PRD filename, e.g., PRD-001)
  • Previous run archived (if prd.json exists with different branchName, archive it first)
  • Each story is completable in one iteration (small enough)
  • Stories are ordered by dependency (schema to backend to UI)
  • Every story has "Typecheck passes" as criterion
  • UI stories have "Verify in browser using dev-browser skill" as criterion
  • Acceptance criteria are verifiable (not vague)
  • No story depends on a later story
  • Complex stories have relevant researchTopics
  • All stories have researchCompleted: false initially
  • changeLog initialized as empty array

Research Topics Guidelines

When to add research topics:

  • Story uses unfamiliar library → "How to use [library] for [task]"
  • Multiple approaches possible → "Compare [approach A] vs [approach B]"
  • Performance matters → "Performance implications of [approach]"
  • Existing patterns unknown → "Existing patterns for [feature] in codebase"

When to skip research topics:

  • Simple CRUD operations
  • Copy-paste from existing similar code
  • Well-understood patterns already used in project
  • Story builds directly on previous story's learnings

© YougLin-dev, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/prd-converter of YougLin-dev/Aha-Loop.

Open the folder on GitHubat commit 8d799b2

Compare with similar skills

Prd Converter next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Prd Converter compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Prd Converter this skillYougLin-dev/Aha-Loop181—~2.6kAutomated safety check: PassMIT
CCPM Project Managementautomazeio/ccpm8.4k—~1.1kAutomated safety check: PassMIT
Ralph Tui Create Beadssubsy/ralph-tui2.5k1 repos~2.6kAutomated safety check: PassMIT
Trellis Brainstormanjiemo/SunnyBeach1787 repos~4kAutomated safety check: PassApache-2.0
Ralph Tui Create Beads Rustsubsy/ralph-tui2.5k1 repos~2.8kAutomated safety check: PassMIT
Ralph Tui Create JSONsubsy/ralph-tui2.5k1 repos~2.6kAutomated safety check: PassMIT

Similar skills

  • Runs a spec-driven workflow from PRD to epic to GitHub issues to parallel agents, with status, standup and blocked-work reports from bundled scripts.

    8.4k GitHub stars~1.1k tokensUpdated 6 mo ago
    Product & Project ManagementAuto-check passed
  • Ralph Tui Create Beads

    subsy/ralph-tui

    Convert PRDs to beads for ralph-tui execution. An agent skill from subsy/ralph-tui.

    2.5k GitHub starsUsed in 1 repo~2.6k tokens
    Product & Project ManagementAuto-check passed
  • Trellis Brainstorm

    anjiemo/SunnyBeach

    Guides collaborative requirements discovery before implementation.

    178 GitHub starsUsed in 7 repos~4k tokens
    Product & Project ManagementAuto-check passed
  • Convert PRDs to beads for ralph-tui execution using beads-rust (br CLI).

    2.5k GitHub starsUsed in 1 repo~2.8k tokens
    Product & Project ManagementAuto-check passed
  • Ralph Tui Create JSON

    subsy/ralph-tui

    Convert PRDs to prd.json format for ralph-tui execution. An agent skill from subsy/ralph-tui.

    2.5k GitHub starsUsed in 1 repo~2.6k tokens
    Product & Project ManagementAuto-check passed
  • Prd Generator

    jamesrochabrun/skills

    Generate comprehensive Product Requirements Documents (PRDs) for product managers.

    216 GitHub starsUsed in 2 repos~3.8k tokens
    Product & Project ManagementAuto-check passed

More from YougLin-dev/Aha-Loop

All 15 skills in this repo
  • Architect

    YougLin-dev/Aha-Loop

    Designs system architecture and selects technology stack based on vision analysis.

    181 GitHub stars~2.2k tokensUpdated 8 mo ago
    Auto-check passed
  • Doc Review

    YougLin-dev/Aha-Loop

    Reviews and cleans up outdated documentation. An agent skill from YougLin-dev/Aha-Loop.

    181 GitHub stars~1.5k tokensUpdated 8 mo ago
    Auto-check passed
  • God Consensus

    YougLin-dev/Aha-Loop

    Guides God Committee members through consensus-building for collective decisions.

    181 GitHub stars~2k tokensUpdated 8 mo ago
    Auto-check passed
  • God Intervention

    YougLin-dev/Aha-Loop

    Guides God Committee members through executing interventions.

    181 GitHub stars~2.3k tokensUpdated 8 mo ago
    Auto-check passed
  • God Member

    YougLin-dev/Aha-Loop

    Defines God Committee member behavior and responsibilities with oversight authority.

    181 GitHub stars~1.6k tokensUpdated 8 mo ago
    Auto-check passed
  • Parallel Explore

    YougLin-dev/Aha-Loop

    Guides parallel exploration of multiple implementation approaches using git worktrees.

    181 GitHub stars~1.9k tokensUpdated 8 mo ago
    Auto-check passed

Questions about Prd Converter

What does Prd Converter do?

Converts PRDs to prd.json format for Aha Loop autonomous execution. Prd Converter is an agent skill from YougLin-dev/Aha-Loop.json format for Aha Loop autonomous execution.

When should I use Prd Converter?

Prd Converter fits situations like: converting existing PRDs to JSON format; create prd.json; aha-loop format.

How do I install Prd Converter in Claude Code?

Run `npx skills add YougLin-dev/Aha-Loop --skill prd-converter -a claude-code`. Or copy the skill folder (.agents/skills/prd-converter in YougLin-dev/Aha-Loop) into .claude/skills/prd-converter in your project. Claude Code loads it when a task matches its description.

How do I install Prd Converter in Codex?

Run `npx skills add YougLin-dev/Aha-Loop --skill prd-converter -a codex`. Or copy the skill folder (.agents/skills/prd-converter in YougLin-dev/Aha-Loop) into .agents/skills/prd-converter in your project. Codex loads it when a task matches its description.

Can I use Prd Converter in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add YougLin-dev/Aha-Loop --skill prd-converter -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/prd-converter, .gemini/skills/prd-converter, .github/skills/prd-converter and .opencode/skills/prd-converter in your project.

What does Prd Converter need to run?

SKILL.md names no scripts, command-line tools or credentials: Prd Converter is instructions for the agent only.

Does Prd Converter access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Prd Converter safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Prd Converter use?

Prd Converter is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Prd Converter use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Prd Converter?

Skills that share tags, products or a category with Prd Converter: CCPM Project Management (automazeio/ccpm, 8.4k stars), Ralph Tui Create Beads (subsy/ralph-tui, 2.5k stars), Trellis Brainstorm (anjiemo/SunnyBeach, 178 stars) and Ralph Tui Create Beads Rust (subsy/ralph-tui, 2.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Prd Converter?

YougLin-dev (a GitHub user) maintains it in YougLin-dev/Aha-Loop, which has 181 GitHub stars. The repository holds 15 skills in this directory. The repository was last updated on February 3, 2026.

Source: YougLin-dev/Aha-Loop on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.