Format for User Stories and Job Stories Skills in the pm-skills Repository

The pm-skills repository defines two distinct Markdown-based skill modules—user-stories and job-stories—that generate backlog items using standardized templates, with user stories following the "As a [role], I want [action], so that [benefit]" pattern and job stories utilizing the "When [situation], I want [motivation], so I can [outcome]" format.

The phuryn/pm-skills repository provides structured product management skill definitions that enforce consistent output formats for backlog generation. Located under pm-execution/skills/, these skill files specify exact field requirements, syntax patterns, and acceptance criteria structures for both user-centric and job-centric story formats.

User Stories Skill Format

The user-stories skill, defined in pm-execution/skills/user-stories/SKILL.md, implements the classic INVEST checklist and the Three C's framework (Card, Conversation, Confirmation). This ensures each generated story is independent, negotiable, valuable, estimable, small, and testable.

Template Structure

Each user story output must contain four mandatory fields formatted in Markdown:

**Title:** [Feature name]

**Description:** As a [user role], I want to [action], so that [benefit].

**Design:** [Link to design files]

**Acceptance Criteria:**
1. [Clear, testable criterion]
2. [Observable behavior]
3. [System validates correctly]
4. [Edge-case handling]
5. [Performance or accessibility consideration]
6. [Integration point]

The Description field strictly follows the Connextra template: "As a [user role], I want [action], so that [benefit]." The Acceptance Criteria section requires a numbered list of 4–6 items that are concrete, testable, and cover edge cases, performance constraints, and integration points.

User Story Example

The following example from pm-execution/skills/user-stories/SKILL.md demonstrates a fully populated template:

**Title:** Recently Viewed Section  

**Description:** As an Online Shopper, I want to see a "Recently viewed" section on the product page so that I can easily revisit items I considered.  

**Design:** [Figma link]  

**Acceptance Criteria:**
1. The section appears at the bottom of the product page for users who have viewed ≥ 1 product.
2. It is omitted on a user's first product-page visit.
3. The current product is excluded from the displayed items.
4. Each card shows image, title, price, and "Viewed X minutes ago".
5. Clicking a card navigates to the corresponding product page.

Job Stories Skill Format

The job-stories skill, documented in pm-execution/skills/job-stories/SKILL.md, adopts the Jobs-to-Be-Done (JTBD) methodology. This format shifts focus from user personas to situational contexts and motivations, capturing the circumstances that prompt a user to "hire" a product.

Template Structure

Each job story output follows this Markdown template:

**Title:** [Job outcome or result]

**Description:** When [situation], I want to [motivation], so I can [outcome].

**Design:** [Link to design files]

**Acceptance Criteria:**
1. [Situation is properly recognized]
2. [System enables the desired motivation]
3. [Progress or feedback is visible]
4. [Outcome is achieved efficiently]
5. [Edge cases are handled gracefully]
6. [Integration and notifications work]

The Description field uses the JTBD syntax: "When [situation], I want [motivation], so I can [outcome]." This structure emphasizes the circumstances triggering the need and the functional progress the user seeks, rather than their demographic role. The acceptance criteria typically include 6–8 items validating situational recognition, motivation support, progress visibility, and outcome achievement.

Job Story Example

This example from pm-execution/skills/job-stories/SKILL.md illustrates the template in practice:

**Title:** Track Weekly Snack Spending  

**Description:** When I'm preparing my weekly allowance for snacks, I want to quickly see how much I've spent so far, so I can make sure I don't run out of money before the weekend.  

**Design:** [Figma link]  

**Acceptance Criteria:**
1. Display a "Weekly Spending Overview" section.
2. Real-time update when a new expense is logged.
3. Progress bar shows 0-100 % of the weekly budget.
4. Remaining budget highlighted in a prominent colour.
5. Breakdown of spending by category.
6. Notification triggers at 80 % of budget usage.

Key Differences Between User Stories and Job Stories

While both skills output Markdown files with Title, Design, and Acceptance Criteria fields, they differ in three critical dimensions:

• Narrative Focus: User stories identify a specific user role and their goal, while job stories describe a situational trigger and the progress the user wants to make.
• Sentence Structure: User stories use "As a... I want... so that..."; job stories use "When... I want... so I can..."
• Acceptance Criteria Depth: Job stories typically require 6–8 criteria covering situational recognition and outcome validation, whereas user stories standardize on 4–6 criteria focused on functionality and edge cases.

Summary

• Both skills are defined in pm-execution/skills/ with individual SKILL.md files for user-stories and job-stories.
• User stories follow the INVEST principles and Connextra format ("As a... I want... so that...").
• Job stories follow the JTBD format ("When... I want... so I can...").
• Each output requires a Title, Description, Design link, and numbered Acceptance Criteria (4–8 items).
• The pm-execution/README.md file provides an overview of both skill modules.

Frequently Asked Questions

What is the difference between user stories and job stories in pm-skills?

User stories focus on defining functionality from the perspective of a specific user role using the format "As a [role], I want [action], so that [benefit]." Job stories, conversely, focus on the situational context and motivation using the JTBD format "When [situation], I want [motivation], so I can [outcome]." The former emphasizes who is using the feature, while the latter emphasizes why they need it and under what circumstances.

Where are the skill templates defined in the repository?

The templates are stored in pm-execution/skills/user-stories/SKILL.md for user stories and pm-execution/skills/job-stories/SKILL.md for job stories. Both files contain the exact Markdown syntax, field definitions, and example outputs that the skill modules use to generate consistent backlog items.

How many acceptance criteria should each story include?

According to the source templates, user stories should include 4–6 acceptance criteria, while job stories typically require 6–8 criteria. These numbered lists must be clear, testable, and cover edge cases, performance considerations, validation rules, and integration points relevant to the specific format.

Can I customize the format for specific projects?

The skill files define the standard output format expected by the pm-skills system. While the repository provides the structured template, individual implementations can populate the bracketed fields with project-specific data. However, modifying the core template structure (the four required fields: Title, Description, Design, and Acceptance Criteria) would require updating the respective SKILL.md files in the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}