Agent Skills: PRD Skill - Create Agent-Friendly Tickets

PRD Skill - Create Agent-Friendly Tickets

You are an expert at breaking down features into well-structured, agent-friendly Linear tickets.

When to Use

Use this skill when:

• Planning a new feature
• Breaking down a large task into sub-issues
• Creating tickets that AI agents will implement

Process

1. Understand the Request

   • Ask clarifying questions if the scope is unclear
   • Identify the core problem being solved

2. Create the Epic/Parent Issue Give it a clear, action-oriented title and a body following the canonical spec template in standards/issue-spec.md — problem, desired outcome, requirements (must-have vs nice-to-have), testable success criteria, boundaries.

   Create it through ~/.claude/scripts/linear-create-child.sh with - for the parent (top-level), never a bare linear-cli issues create. A bare create passes no workflow state, and on a triage-enabled team the team default is Triage — where next-candidates.sh's WORKABLE_STATES (Backlog/Planned/Todo) cannot see it, so a certified epic is invisible to /next and /auto with nothing reporting the omission. The helper resolves a workable state and verifies it landed.

   On a run that will create sub-issues, pass the workspace epic label in the helper's label slot — the parent is a delegated epic whose work its children carry, and certification (Step 5) leaves that slot free on batch runs. Neither the epic nor its sub-issues carries a routing label at create on such a run, so each create passes the leading --allow-unrouted: the helper refuses a label slot with no routing label otherwise, and the flag records that Step 5 certifies. A single-issue run is not an epic: no epic label, its slot carries specified per Step 5, and it needs no flag.

3. Break Down into Sub-Issues Each sub-issue body is itself a spec (same template) and should:

   • Be completable in one focused session (<150k tokens of context)
   • Have clear success criteria stated as observable outcomes
   • Define boundaries (what's in/out of scope — deliverable exclusions, not mechanism guesses; a mechanism-exclusion only records containment the human in this conversation chose, marked (decided: <who/why>) — standards/issue-spec.md § Out of Scope bounds the deliverable, never the evidence)
   • Be executable by exactly one kind of worker: an unattended agent (a repo-shaped deliverable whose success criteria the project's quality gates can verify) or a human (outreach, ops, confirmation passes — labeled human at Step 5). Never bundle both: an issue that fuses a fully-specified schema to a confirmation pass the plan itself calls human-in-the-loop work is declined whole by /auto, and the shippable slice sits idle. When a flow needs both, split at the handoff and wire the edge by what the downstream step does without the human's: blocks where it would be wrong (confirm → enforce — enforcing an unconfirmed registry acts on data nobody vetted), related where it merely waits (build → confirm) — the human carve-out in standards/issue-spec.md § Certification includes collision edges.
   • Depend on no unstated mapping or unenumerated scope: "the appropriate owner" and "everywhere transactions name an organization" are decisions wearing requirement clothes, and /auto declines them — enumerate or decide them in this conversation, before the issue exists; criteria that assert production state no test suite can verify belong on a human issue, not an agent one.

4. Set Up Dependencies Use linear-cli relations add <BLOCKER> <BLOCKED> -r blocks to create dependency chains (see Example Commands).

   Then wire each chain-tail sub-issue as a blocker of the parent epic — relations add <SUB> <PARENT> -r blocks for every sub-issue nothing else in the batch depends on (the rest reach the parent transitively, so more edges would be the redundant A→C Step 5's doctrine forbids). An epic's requirements are pointers at its sub-issues, and next-candidates.sh's delegated de-rank fires only once NO child is workable — the end of an epic's life, not its start — so an unwired epic ranks alongside its own open children at full priority and a session that picks it finds nothing to implement. Wired this way the epic surfaces exactly once: after every sub-issue ships, annotated as likely needing closure.

5. Certify First run a collision pass over the batch — every producer attaching specified owes one at attach time (standards/issue-spec.md § Certification includes collision edges). Run the Discovering Related Work searches (the section below) now if they have not been run this session, then check each new issue against its siblings and against the open issues those searches surfaced, at the granularity this skill has: component and feature decomposition, never files, since /prd reads no code. blocks only where the pair is a prerequisite, a same-method collision, or a deliberate increment (the three meanings — standards/issue-spec.md § Certification includes collision edges); at this skill's granularity that is nearly always the prerequisite, one sub-issue building on what another delivers. A pair merely sharing a component, and so likely files, takes related plus a comment. So does a prerequisite whose open collider is uncertified, needs decision, solo, or human — an issue in that state never ships unattended, and a blocks edge behind it strands the new issue invisibly — except a human act the new issue would be wrong without, which blocks it on purpose (the standard's human carve-out; sibling-vs-sibling edges within the batch are unaffected, since every sibling certifies together at this same step); disjoint areas sharing a mechanism → related plus a comment naming the mechanism; no overlap → nothing. Edges step 4 already wired count as resolved here — this pass covers colliding pairs step 4 left unserialized, and never duplicates or reverses a chain edge step 4 already set.

   Then apply the specified label to every created issue — parent and each sub-issue:

   ~/.claude/scripts/linear-add-label.sh ENG-100 specified
   

   specified marks a certified spec — the gate /auto picks up (standards/issue-spec.md). Label post-create rather than via issues create -l, so a label problem can never fail issue creation. On exit 2, surface the helper's create-label pointer and tell the user certification is incomplete.

   One class of sub-issue certifies gated: work only a human can perform — customer outreach, vendor contact, production data remediation, a confirmation pass the body itself assigns to a person. The quality bar tests spec shape, not agent capability, so these pass it and then sit rankable in the certified pool until a fleet session picks one and declines it. Attach human alongside specified here, naming the owner when known — the spec is right, the executor is a person (standards/issue-spec.md); needs decision is the wrong gate for these, since it advertises a pending decision that would hand the issue back to agents. /auto-prep Step 2 applies the identical disposition later, but only after the issue has already spent time rankable.

   A second class certifies cheap: a sub-issue meeting the simple semantics (standards/issue-spec.md § The simple label — risk-low, no open decision) additionally takes simple, which selects /quality-review's lighter tier when a run ships it. Apply it from the decomposition's own reading — a schema-description fix, a locale consolidation, a dead-code deletion — never on a security, human, needs decision, or epic sub-issue; /auto-prep re-audits both directions later.

   linear-create-child.sh's optional label argument already attaches post-create with those same best-effort semantics (id on stdout either way, exit 2 when the attach fails), so passing specified there satisfies this step on a single-issue run only — a run that creates exactly one issue total (an epic with no sub-issues) and so may certify on create; a run creating two or more issues (epic + sub-issues) is a batch and certifies here, at Step 5, after the collision pass. A single-issue run still owes the collision pass — run it (the Discovering Related Work search against open issues; the sibling-vs-sibling half is vacuous with no siblings) immediately after the create that certified it, wiring edges per the same calibration above. This is the accepted attach-then-wire residual window that standards/issue-spec.md § Certification includes collision edges describes, not a gap. When the run creates several issues (an epic with sub-issues), pass epic for the label at create (Step 2) and certify here instead — specified is the pickability gate, so a fleet can pick a sub-issue seconds after it is created, before its siblings exist and before any edge is wired; sequencing has to be mechanical before the label attaches. Re-running the helper above on an issue that already carries it is idempotent — this step is the backstop, not a second mechanism.

Spec Shape

The canonical template and quality bar live in standards/issue-spec.md: Problem → Desired Outcome → Requirements (Must/Nice checkboxes) → Success Criteria (testable checkboxes) → Boundaries (In/Out of Scope). The Problem is a story — a named actor, what they saw, the stake in their units, then the mechanism, sized to the stake, with the measurements it does not carry under ## Evidence (that standard's § The Problem is a story); an epic's Problem leads with the named people its counts summarize.

Specs are problem + outcomes + success criteria only — no implementation planning (/start Step 6 designs the how, in plan mode, at execution time) and no verification-command blocks (project quality gates own that). Checkboxes are load-bearing: /start treats them as requirements and /finish checks them off.

Example Commands

# Create the top-level epic — `-` as the parent means no parent. Same helper as the
# sub-issue below: it resolves and verifies the workflow state, so the epic cannot land
# in Triage and fall out of /next's WORKABLE_STATES unnoticed. `epic` in the label slot:
# this run creates a batch, so the parent is a delegated epic and certification waits for
# step 5, after the collision edges are wired. A single-issue run passes `specified` in
# that position instead (a standalone issue is not an epic) and drops --allow-unrouted,
# which a batch create needs because its routing label arrives at step 5.
#   ...write the description to tmp/prd-description.md via the Write tool...
~/.claude/scripts/linear-create-child.sh --allow-planned --allow-unrouted - ENG Planned "User Authentication System" tmp/prd-description.md epic 2

# Create a sub-issue linked to a parent. `linear-cli issues create` has no --parent
# flag (set the parent's UUID via `--data` parentId instead), but prefer the helper — it
# links via `relations parent` and verifies the link, failing on an orphan. Write the body to a file first.
#   ...write the description to tmp/sub-issue-description.md via the Write tool...
~/.claude/scripts/linear-create-child.sh --allow-planned --allow-unrouted ENG-100 ENG Planned "Add JWT refresh tokens" tmp/sub-issue-description.md

# Set a blocking dependency: ENG-101 blocks ENG-102 (i.e. ENG-102 is blocked by ENG-101).
# Use `-r blocks` with the blocker FIRST — `-r blocked-by` 400s (linear skill gotcha #10).
linear-cli relations add ENG-101 ENG-102 -r blocks

# Certify each created issue (read-merge-set — `issues update -l` alone would replace the label set)
~/.claude/scripts/linear-add-label.sh ENG-100 specified
~/.claude/scripts/linear-add-label.sh ENG-101 specified

Body text longer than one line goes to tmp/ and in through ~/.claude/scripts/linear-stdin.sh, never via <, cat |, $() or a heredoc into linear-cli — permission wildcards do not match through shell operators (standards/linear-workflow.md § Passing File Content to Linear CLI). Piping linear-cli output to jq is fine.

Discovering Related Work

Before creating tickets, search for existing related work:

# Find existing work on this topic. NOTE: `search issues` has no --team flag — it
# searches the whole workspace. Scope by team with `issues list --team ENG` or the api.
linear-cli search issues "authentication"

# Look for related work / potential blockers, then inspect dependencies via the graph
linear-cli search issues "user database"
~/.claude/scripts/linear-deps-graph.sh --team ENG    # {nodes, edges} — filter with jq (linear skill gotcha #2); blocked chains: scripts/fleet-blockers.sh

Pro tip: After creating tickets, establish dependencies directly with linear-cli relations add <BLOCKER> <BLOCKED> -r blocks (blocker first; -r blocked-by 400s — linear skill gotcha #10).

Best Practices

1. Size tickets appropriately - Each should be 1-4 hours of focused work
2. State success criteria as observable outcomes - Verification commands and technical approach belong to /start, not the ticket
3. Be explicit about scope - Prevent scope creep with clear boundaries
4. Certify every ticket - Process step 5 applies the specified label; /auto only ships certified issues
5. Establish dependencies - Use linear-cli relations add <BLOCKER> <BLOCKED> -r blocks to show work order
6. Search first - Check for existing related issues before creating duplicates