inclusive-user-stories
Write user stories that account for disability and diverse abilities from the start. Use when writing user stories, acceptance criteria, jobs to be done, or requirements. Triggers on: user story, user stories, acceptance criteria, jobs to be done, JTBD, requirements, as a user I want, definition of done, story writing.
- Installs
- 72
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/owl-listener/inclusive-design-skills --skill inclusive-user-stories- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads inclusive-user-stories automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Inclusive User Stories
Write user stories where accessibility is part of the acceptance criteria from the start — not added later as a separate ticket.
The Problem
Most user stories are written as: "As a user, I want to filter search results so I can find what I need."
This assumes a user who can see the filters, click small targets, read the labels, and process the results visually. It silently excludes anyone who interacts differently.
The Fix
Don't write separate "accessibility stories." Build inclusion into every story's acceptance criteria.
Story Structure
The Story
Keep the standard format: "As a [user], I want to [action] so that [outcome]."
But be specific about the user when it matters:
- "As a keyboard-only user, I want to filter results using arrow keys and Enter so that I can narrow my search without a mouse."
- "As a screen reader user, I want filter changes to be announced so that I know the results have updated."
Inclusive Acceptance Criteria
For every user story, add these checks to the acceptance criteria:
Keyboard:
- Feature is fully operable with keyboard alone
- Focus order is logical
- Focus is visible on every interactive element
Screen reader:
- All controls have accessible names
- State changes are announced
- Dynamic content updates use aria-live
Visual:
- Information is not conveyed by colour alone
- Text meets minimum contrast (4.5:1 for normal, 3:1 for large)
- Content is readable at 200% zoom
Motor:
- Touch targets are at least 44×44px
- No time-dependent interactions without alternatives
- No precision-dependent interactions without alternatives
Cognitive:
- Instructions are in plain language
- Error messages explain what to do, not just what went wrong
- User can undo or recover from mistakes
Patterns for Common Stories
"As a user, I want to complete a form"
Add:
- Labels are visible and associated with fields
- Required fields are indicated visually and programmatically
- Errors appear inline next to the field, not just in a banner
- Form can be completed with keyboard, touch, or voice
"As a user, I want to view a dashboard"
Add:
- Data is not conveyed by colour alone (patterns, labels, values)
- Charts have text summaries
- Dashboard is navigable by keyboard with logical tab order
- Key metrics are announced to screen readers
"As a user, I want to receive a notification"
Add:
- Notification is visual AND programmatically announced
- User can control notification preferences
- Notification does not disappear before it can be read
- Notification does not block other interactions
How to Audit Existing Stories
- Read each story and ask: who does this exclude?
- Check acceptance criteria for keyboard, screen reader, visual, motor, and cognitive requirements
- Flag any story that assumes a single input method or sense
- Add missing criteria — don't create separate stories
Assessment Questions
- Do acceptance criteria include keyboard, screen reader, and cognitive requirements?
- Are accessibility criteria part of the definition of done?
- Has each story been checked for assumptions about ability?
- Are there any stories that only work for one input method?
FAQ
What does the inclusive-user-stories skill do?
Write user stories that account for disability and diverse abilities from the start. Use when writing user stories, acceptance criteria, jobs to be done, or requirements. Triggers on: user story, user stories, acceptance criteria, jobs to be done, JTBD, requirements, as a user I want, definition of done, story writing.
How do I install inclusive-user-stories?
Run npx skills add https://github.com/owl-listener/inclusive-design-skills --skill inclusive-user-stories in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/inclusive-user-stories/ (personal) or .claude/skills/inclusive-user-stories/ (project).
Which AI agents can use inclusive-user-stories?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is inclusive-user-stories safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains inclusive-user-stories?
It is published by owl-listener in owl-listener/inclusive-design-skills. It has 72 recorded installs.
More from owl-listener/inclusive-design-skills
plain-language-design
owl-listener/inclusive-design-skills
Write and review content for plain language accessibility. Use when writing interface copy, error messages, instructions, onboarding text, help content, legal or medical information, forms, or any user-facing text. Triggers on: plain language, reading level, simplify text, jargon, hard to understand, nobody reads this, unclear copy, rewrite, too complicated, ESL, literacy, readability.
keyboard-navigation
owl-listener/inclusive-design-skills
Design keyboard navigation and focus management for users who cannot or prefer not to use a mouse or touch screen. Use when designing any interactive interface — forms, menus, modals, tabs, carousels, drag-and-drop, data tables, or custom components. Triggers on: keyboard, focus, tab order, focus trap, skip link, arrow keys, keyboard shortcut, can't use mouse, motor disability, switch access, focus indicator, focus ring.
cognitive-load-assessment
owl-listener/inclusive-design-skills
Assess and reduce cognitive load in interfaces, flows, and content. Use when designing or reviewing any multi-step process, complex form, dashboard, decision flow, or information-dense screen. Triggers on: cognitive load, too complex, overwhelmed, too many steps, decision fatigue, confusing, information overload, simplify this flow. Applies to any interface where users must think, decide, or remember.
responsive-review
owl-listener/inclusive-design-skills
Review responsive and flexible layout for accessibility across devices, zoom levels, and orientations. Chains: responsive-accessibility, flexible-typography, information-density. Use when testing an existing interface across screen sizes and zoom levels for accessibility.
user-preference-respect
owl-listener/inclusive-design-skills
Design interfaces that detect and respond to system-level user preferences. Use when implementing dark mode, reduced motion, high contrast, text scaling, or any user preference that affects how the interface renders. Triggers on: user preference, system preference, prefers-reduced-motion, prefers-contrast, prefers-color-scheme, forced-colors, media query, user settings, system settings, accessibility settings, OS settings.
error-prevention-recovery
owl-listener/inclusive-design-skills
Design error prevention, error messages, and recovery flows for cognitive accessibility. Use when designing forms, checkout flows, account creation, settings, data entry, or any flow where users can make mistakes. Triggers on: error handling, error messages, form errors, validation, users make mistakes, users abandon, error recovery, undo, forgiving design.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.