3skill

Create and manage Product Requirements Documents (PRDs) by defining user stories with verifiable acceptance criteria and tracking progress by priority order.

Security Scan

The skill's files and instructions are broadly consistent with a PRD/agentic workflow, but embedded examples encourage unattended agent loops and disabling agent permissions — behaviors that increase risk and deserve review before use.

Purpose & Capability

Name/description (create/manage PRDs and user stories) align with the provided templates and runtime instructions: prd.json, progress.txt, story lifecycle, and git workflow. The files and examples relate to coding work and PRD execution, so requested capabilities match purpose.

Instruction Scope

SKILL.md and references direct agents to read and modify local repo files (prd.json, progress.txt), create/check out branches, implement code, run checks, commit changes, and update prd.json. Those actions fit the stated goal but carry high-impact side effects (modifying code, committing). More importantly, examples include an unattended infinite loop and a concrete example using `claude --dangerously-skip-permissions`, which explicitly suggests bypassing safety checks — this is out-of-band risk and should be treated with caution.

Install Mechanism

Instruction-only skill with no install spec, no binaries, and no external downloads. Nothing will be written to disk by the skill itself; risk from install mechanism is minimal.

Credentials

The skill declares no environment variables, no credentials, and no config paths. The documentation references agent CLIs (Claude, OpenCode) and git but does not request unrelated secrets or credentials in metadata.

Persistence & Privilege

Skill is not always-enabled and does not request persistent privileges, which is appropriate. However, its documentation encourages running autonomous agent loops that modify a repository and suggests disabling agent permission checks in examples — combining autonomous execution with instructions to bypass safety increases practical risk even though the skill metadata itself does not request elevated platform privileges.

What to consider before installing

This skill is essentially a PRD template + agent-run instructions. That is coherent, but be careful before using it autonomously: 1) Do not run infinite unattended loops against your main repo; use isolated worktrees or throwaway test repos. 2) Never use flags like `--dangerously-skip-permissions` or other options that bypass agent safety — they defeat platform protections. 3) Require human review of any agent-made commits (use pull requests, branch protection, CI). 4) Backup your repo and run agents in a sandboxed environment first. 5) If you intend to allow an agent to commit code, restrict its scope (single worktree, limited filesystem access) and audit progress.txt and prd.json updates. These steps will reduce the risk of unintended or damaging automated changes.

PRD Skill

Create and manage Product Requirements Documents (PRDs) for feature planning.

What is a PRD?

A PRD (Product Requirements Document) is a structured specification that:

1. Breaks a feature into small, independent user stories
2. Defines verifiable acceptance criteria for each story
3. Orders tasks by dependency (schema → backend → UI)

Quick Start

1. Create/edit agents/prd.json in the project
2. Define user stories with acceptance criteria
3. Track progress by updating passes: false → true

prd.json Format

{
  "project": "MyApp",
  "branchName": "ralph/feature-name",
  "description": "Short description of the feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column: 'high' | 'medium' | 'low'",
        "Generate and run migration",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Field Descriptions

Field	Description
project	Project name for context
branchName	Git branch for this feature (prefix with ralph/)
description	One-line feature summary
userStories	List of stories to complete
userStories[].id	Unique identifier (US-001, US-002)
userStories[].title	Short descriptive title
userStories[].description	"As a [user], I want [feature] so that [benefit]"
userStories[].acceptanceCriteria	Verifiable checklist items
userStories[].priority	Execution order (1 = first)
userStories[].passes	Completion status (false → true when done)
userStories[].notes	Runtime notes added by agent

Story Sizing

Each story should be completable in one context window.

✅ Right-sized:

• 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 large (split these):

• "Build the entire dashboard" → Split into: schema, queries, UI, filters
• "Add authentication" → Split into: schema, middleware, login UI, session

Story Ordering

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

Acceptance Criteria

Must be verifiable, not vague.

✅ Good:

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Typecheck passes"

❌ Bad:

• "Works correctly"
• "User can do X easily"

Always include: "Typecheck passes"

Progress Tracking

Update passes: true when a story is complete. Use notes field for runtime observations:

"notes": "Used IF NOT EXISTS for migrations"

Quick Reference

Action	Command
Create PRD	Save to agents/prd.json
Check status	`cat prd.json
View incomplete	`jq '.userStories[]

Resources

See references/ for detailed documentation:

• agent-usage.md - How AI agents execute PRDs (Claude Code, OpenCode, etc.)
• workflows.md - Sequential workflow patterns
• output-patterns.md - Templates and examples