5skill

Create and manage Product Requirements Documents with user stories, verifiable acceptance criteria, and ordered implementation tasks.

Security Scan

The skill's PRD content matches its stated purpose, but the runtime instructions promote autonomous agents that modify code (including an infinite loop example and an explicit flag to bypass agent permissions), and the metadata omits required tooling — these inconsistencies raise security and operational concerns.

Purpose & Capability

The README and templates are coherent with a PRD/agent-execution workflow: they define prd.json, user stories, and how to track progress. However the SKILL.md and references assume use of CLIs (claude, opencode, git, jq, dev-browser) and autonomous agent execution; the skill metadata declares no required binaries or credentials, which is an omission (missing declared dependencies/tools needed to run the documented flows).

Instruction Scope

The instructions go beyond authoring PRDs: they include an unattended agentic loop (while :; do claude --print --dangerously-skip-permissions ... done) that tells an agent to read prd.json, check out branches, implement code, run tests/typechecks, commit changes, and update progress files. That pattern can autonomously change repositories and the explicit use of '--dangerously-skip-permissions' instructs operators to bypass permissions/safety checks — a clear operational and security risk.

Install Mechanism

This is an instruction-only skill with no install spec or code files, so nothing is written to disk by the skill itself. That lowers installation risk, but the documentation expects external CLIs and tools to be present.

Credentials

The skill requests no environment variables or credentials, which is good from a secrets-exfiltration perspective. However the instructions assume use of agent CLIs and git operations that normally require local tooling and possibly API tokens; the omission of any declared required credentials/tools is a proportionality/metadata mismatch that could hide important operational prerequisites.

Persistence & Privilege

The skill itself is not marked 'always:true', but the provided agent usage patterns encourage running autonomous, long-running loops that repeatedly invoke agents to edit code and commit changes. Combined with the recommendation to bypass permission checks, this increases blast radius if run unattended. The skill does not request explicit elevated platform privileges, but operational guidance effectively advocates persistent autonomous execution.

Scan Findings in Context

[cli-bypass-permissions-flag] unexpected: The references include the exact command-line flag '--dangerously-skip-permissions' which instructs bypassing agent permission/safety checks. This is not expected for a PRD authoring skill and is a security concern.

What to consider before installing

This skill's PRD templates and guidance are generally useful for planning, but the runtime documentation contains risky operational instructions. Before using it: (1) Do NOT run the provided 'unattended agentic loop' as-is — it can autonomously modify your repo and run indefinitely. (2) Never use the '--dangerously-skip-permissions' flag or other directives that bypass agent safety checks. (3) Run any agentic execution in an isolated sandbox or throwaway clone, with human review steps enabled. (4) Verify and restrict any CLIs or tokens the agent would need (claude, opencode, git, jq, dev-browser) and add those requirements to the skill metadata. (5) Consider adding explicit human-in-the-loop approval before commits, and back up your repository before testing. If you need the automation, require the skill to declare required binaries/credentials and remove instructions that bypass permissions.

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