4skill

Create and manage Product Requirements Documents by defining user stories with acceptance criteria, ordering tasks by dependencies, and tracking progress.

Security Scan

The skill's PRD content fits its stated purpose, but the runtime instructions encourage unattended/autonomous agent loops and bypassing permission checks while not declaring the credentials or environment access that those actions require — this mismatch is risky and deserves caution.

Purpose & Capability

The name/description (PRD authoring and tracking) align with the included JSON schema, templates, and workflows. However the references and runtime instructions assume the skill will invoke external agent CLIs (e.g., claude, opencode), perform git worktree operations, and commit code — capabilities consistent with 'implementing stories' but not explicitly declared (no required binaries, no required env vars, no config paths). The omission of expected requirements (agent CLI availability, git access) is noteworthy.

Instruction Scope

SKILL.md and references instruct agents to read and update prd.json and progress.txt (expected) but also recommend running persistent agent loops (example: while :; do claude --print --dangerously-skip-permissions ...) and to auto-checkout/create git branches and commit code. The explicit use of a --dangerously-skip-permissions flag and an infinite unattended loop grants wide autonomous power outside the skill metadata and is out-of-scope for a simple PRD authoring skill.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk by the skill itself. This lowers installation risk.

Credentials

The skill declares no required environment variables, yet the instructions assume presence of external CLIs (claude, opencode) which typically require API keys or credentials, and also assume git credentials for creating branches and committing. The skill does not declare or justify these credentials or any config paths, creating a mismatch between declared requirements and actual instructions.

Persistence & Privilege

The skill is not force-enabled (always:false), but its documentation explicitly encourages running indefinite unattended agent loops that bypass permissions and autonomously modify a repository. That pattern increases blast radius if the user follows the instructions; combined with the instruction to skip permission checks, it is a meaningful operational risk.

What to consider before installing

This skill's templates and JSON schema are coherent for creating and tracking PRDs, but its runtime docs instruct running autonomous agent loops and a CLI flag that bypasses permissions. Before using: (1) Do NOT run the example infinite loop or any command containing --dangerously-skip-permissions unless you fully trust the agent binary and environment. (2) Expect to provide git credentials and agent/API keys locally — the skill does not declare or manage them. (3) If you want automation, run the agent in a tightly sandboxed environment or CI with least privilege and audit logs, and require manual approval before commits. (4) Inspect any agent prompts and progress.txt entries before allowing automated commits. If you cannot or do not want to run an autonomous agent with repository access, use the PRD templates manually instead.

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