SkillCheck validator, Cursor exports, and per-agent installers (#27)
Three more learnings from alirezarezvani/claude-skills, applied: 1. SkillCheck validator (scripts/skillcheck.mjs) — validates every SKILL.md against the authoring standard (frontmatter, name/folder match, trigger + produces clauses, required headings) plus tier referential integrity. Errors fail CI; --strict fails on warnings too. New skillcheck.yml workflow and a SkillCheck status badge in the README. Current: 0 errors / 14 advisory warnings across 172 skills. 2. Cursor export platform — build-exports.mjs now generates exports/cursor/<bundle>/<skill>/<skill>.mdc rule files. The PLATFORMS registry now supports per-skill filenames (file as a function). 3. Per-agent installers — scripts/install.sh unifies install for claude/hermes/codex/openclaw/cursor (--link, --target, --dry-run, --list). Curl-able one-liners codex-install.sh, openclaw-install.sh, and cursor-install.sh clone the library and install in a single command. README documents the one-line installs and Cursor exports; CHANGELOG and the authoring standard updated. Claude-Session: https://claude.ai/code/session_016JWn5jRD5tcEFKrubjQ6Px Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
mohitagw15856
GitHub
@@ -0,0 +1,227 @@
|
||||
---
|
||||
description: "Write well-structured user stories with acceptance criteria and edge cases. Use when asked to write user stories, create tickets from a feature brief, convert a PRD into stories, or write acceptance criteria. Produces ready-to-estimate stories in the standard format with clear acceptance criteria, edge cases, and definition of done."
|
||||
globs:
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# User Story Writer Skill
|
||||
|
||||
This skill produces production-ready user stories from a feature brief, PRD section, or verbal description. Each story follows the standard format with a clear who/what/why, behavioural acceptance criteria in Given/When/Then format, edge cases, and definition of done. Output is ready to paste into Jira, Linear, or your planning tool.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or change** to break into stories — paste the brief, PRD section, or describe the feature
|
||||
- **User types / personas** involved (e.g. admin, end user, guest, API consumer)
|
||||
- **Scope** — are we writing one story or decomposing an epic into a full set of stories?
|
||||
- **Acceptance criteria format preference** — Given/When/Then, bullet checklist, or both?
|
||||
- **Technical constraints or notes** — anything the engineering team has flagged that should shape the stories
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each story:
|
||||
|
||||
---
|
||||
|
||||
## Story: [Short title — verb + noun, e.g. "Filter search results by date range"]
|
||||
|
||||
**Epic:** [Parent epic name — e.g. "Advanced Search"]
|
||||
**Story ID:** [Jira/Linear ID — leave blank if not yet created]
|
||||
**Priority:** [P1 / P2 / P3]
|
||||
**Story points:** [Leave blank — for engineering to estimate]
|
||||
|
||||
---
|
||||
|
||||
### User Story
|
||||
|
||||
> **As a** [specific user type — not "user"],
|
||||
> **I want to** [concrete action they want to take],
|
||||
> **So that** [the outcome they achieve — business value, not feature description].
|
||||
|
||||
**Example:**
|
||||
> As an **account manager**,
|
||||
> I want to **filter my client list by last contact date**,
|
||||
> so that I **can quickly identify clients I haven't spoken to in over 30 days and prioritise outreach**.
|
||||
|
||||
---
|
||||
|
||||
### Context
|
||||
|
||||
[1–3 sentences of context that aren't in the user story itself: when does this story matter, what triggers the need, how does it fit into a larger flow. This helps engineers understand why before they ask.]
|
||||
|
||||
---
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
**Format: Given / When / Then**
|
||||
|
||||
Each criterion tests one specific behaviour. Write one GWT per observable outcome — not one GWT for the whole feature.
|
||||
|
||||
**AC1: [Short name for this criterion]**
|
||||
```
|
||||
Given [starting state or context]
|
||||
When [user action]
|
||||
Then [observable system behaviour]
|
||||
```
|
||||
|
||||
**AC2: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
**AC3: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
[List scenarios that are non-obvious but must be handled. These become additional ACs or notes to engineering.]
|
||||
|
||||
- [ ] **[Edge case 1]:** [e.g. User applies a date filter that returns 0 results — show empty state with clear messaging and a "clear filters" action]
|
||||
- [ ] **[Edge case 2]:** [e.g. User has >10,000 clients — filter must not degrade load time >200ms]
|
||||
- [ ] **[Edge case 3]:** [e.g. Date filter persists across page refresh — or explicitly should not if that's the decision]
|
||||
- [ ] **[Permission edge case]:** [e.g. Read-only users can see the filter but cannot save filter presets]
|
||||
|
||||
---
|
||||
|
||||
### Out of Scope
|
||||
|
||||
[Explicitly state what this story does NOT cover — prevents scope creep and clarifies where the next story begins.]
|
||||
|
||||
- Saving and sharing filter presets (separate story — see [Story X])
|
||||
- Bulk actions on filtered results
|
||||
- Exporting filtered client list to CSV
|
||||
|
||||
---
|
||||
|
||||
### Definition of Done
|
||||
|
||||
- [ ] Acceptance criteria all pass
|
||||
- [ ] Edge cases handled (or explicitly deferred with a new ticket raised)
|
||||
- [ ] Unit tests written for each AC
|
||||
- [ ] Works on mobile viewport (if applicable)
|
||||
- [ ] Accessibility: keyboard navigable and screen-reader compatible
|
||||
- [ ] Error states are handled and copy approved
|
||||
- [ ] Product and design have reviewed in staging
|
||||
- [ ] No console errors in production build
|
||||
|
||||
---
|
||||
|
||||
## Epic Decomposition Template
|
||||
|
||||
If the user provides an epic or feature brief, decompose it into a full set of stories before writing them:
|
||||
|
||||
**Epic:** [Name]
|
||||
**Goal:** [What outcome does completing this epic achieve?]
|
||||
**Stories:**
|
||||
|
||||
| # | Story | Notes | Dependencies |
|
||||
|---|---|---|---|
|
||||
| 1 | [Core happy path story — the simplest version of the feature that delivers value] | | |
|
||||
| 2 | [Validation / error handling story] | | Depends on #1 |
|
||||
| 3 | [Edge case or power user story] | | Depends on #1 |
|
||||
| 4 | [Admin or configuration story] | | |
|
||||
| 5 | [Performance or scale story — if applicable] | | Depends on #1 |
|
||||
|
||||
**Suggested sprint order:** [Which stories are P1 for MVP? Which can follow in a later sprint?]
|
||||
|
||||
---
|
||||
|
||||
## Common Story Anti-Patterns — and Fixes
|
||||
|
||||
Use these to review stories before handing to engineering:
|
||||
|
||||
| Anti-pattern | Example | Fix |
|
||||
|---|---|---|
|
||||
| **Solution in the story** | "As a user I want a dropdown filter" | Remove the UI decision — "As a user I want to filter by date range" |
|
||||
| **Vague "so that"** | "so that it's easier to use" | Make it specific — "so that I can prioritise outreach without opening each record manually" |
|
||||
| **Too big** | Story covers 5 distinct user flows | Split into separate stories per flow |
|
||||
| **No acceptance criteria** | Story has description only | Add at least 3 GWT criteria before engineering starts |
|
||||
| **ACs that test the solution, not the behaviour** | "Given the dropdown is open, When I select an option" | Test the outcome — "Given I have applied a date filter, When I view my results, Then only clients last contacted in that date range appear" |
|
||||
| **Missing empty state** | No AC for what happens with 0 results | Add it — empty states are part of the feature |
|
||||
| **Missing error state** | No AC for network failure or invalid input | Add error handling ACs explicitly |
|
||||
|
||||
---
|
||||
|
||||
## Example: Full Story Set for a Feature
|
||||
|
||||
**Feature brief:** "Allow users to export their invoice history as a PDF or CSV"
|
||||
|
||||
---
|
||||
|
||||
### Story 1: Export invoice list as CSV
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a CSV file**,
|
||||
> so that I can **import it into our accounting software without manual data entry**.
|
||||
|
||||
**AC1: Successful export**
|
||||
```
|
||||
Given I am on the Invoices page with at least one invoice
|
||||
When I click "Export" and select "CSV"
|
||||
Then a CSV file is downloaded containing all visible invoices with columns: Invoice ID, Date, Amount, Status, Customer Name
|
||||
```
|
||||
|
||||
**AC2: Empty state**
|
||||
```
|
||||
Given I am on the Invoices page with no invoices
|
||||
When I click "Export"
|
||||
Then the export button is disabled and a tooltip reads "No invoices to export"
|
||||
```
|
||||
|
||||
**AC3: Filtered export**
|
||||
```
|
||||
Given I have applied a date filter showing invoices from Jan 2026 only
|
||||
When I click "Export" and select "CSV"
|
||||
Then the export contains only invoices from Jan 2026 — not all invoices
|
||||
```
|
||||
|
||||
**Edge cases:**
|
||||
- [ ] Export with >10,000 invoices — must complete in <30s or show a progress indicator
|
||||
- [ ] Export triggered on mobile — downloads to device's default download location
|
||||
|
||||
**Out of scope:** PDF export (Story 2), scheduled exports (future epic)
|
||||
|
||||
---
|
||||
|
||||
### Story 2: Export invoice list as PDF
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a formatted PDF**,
|
||||
> so that I can **share a professional summary with our accountant**.
|
||||
|
||||
[... ACs follow same pattern ...]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every story has a specific user type — not "a user" or "the system"
|
||||
- [ ] The "so that" explains business value — not just feature description
|
||||
- [ ] Each AC tests one observable outcome — not a bundle of behaviours
|
||||
- [ ] Empty states, error states, and edge cases are explicitly handled
|
||||
- [ ] Out of scope is documented — not assumed
|
||||
- [ ] Stories are independent — they can be shipped individually without depending on unreleased work (except where explicitly noted)
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write user stories from a technical perspective — every story must be from the user's point of view and state their goal
|
||||
- [ ] Do not write acceptance criteria that are untestable — every criterion must have a clear pass/fail condition
|
||||
- [ ] Do not create stories that are too large to complete in a single sprint — break epics into estimable, independently deliverable stories
|
||||
- [ ] Do not omit edge cases — unhappy paths and error states are required, not optional
|
||||
- [ ] Do not skip the Definition of Done — without it, "done" means different things to different people
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write user stories for [feature] from this brief"
|
||||
- "Break this PRD section into user stories with acceptance criteria"
|
||||
- "Convert these feature requirements into Jira tickets"
|
||||
- "Write the user stories and ACs for [feature name]"
|
||||
- "Decompose this epic into individual stories ready for sprint planning"
|
||||
Reference in New Issue
Block a user