From silver-bullet
Enforces usability-first design principles for intuitive APIs, clear error messages, and progressive disclosure. Use during planning and review to ensure systems are easy to use.
How this skill is triggered — by the user, by Claude, or both
Slash command
/silver-bullet:usabilityThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Every design, plan, and implementation MUST be intuitive, forgiving, and self-documenting. Whether the consumer is an end user clicking a button or a developer calling an API, the experience MUST minimize confusion, surprise, and frustration.
Every design, plan, and implementation MUST be intuitive, forgiving, and self-documenting. Whether the consumer is an end user clicking a button or a developer calling an API, the experience MUST minimize confusion, surprise, and frustration.
Why this matters: Systems that are hard to use don't get used — or they get used wrong. Poor usability causes support tickets, workarounds, data entry errors, and abandonment. The most technically correct system is worthless if nobody can figure out how to use it.
When to invoke: During PLANNING (after /silver:context, before /silver:plan) and during REVIEW (as part of code review criteria). This skill applies to user interfaces, APIs, CLIs, configuration files, error messages, and documentation.
Everything MUST behave as users expect. If a user predicts what will happen before they act, the design is working.
calculateTotal() not runAlgorithm3().--verbose, don't use --detailed-output.getUser() returns a user object, getOrder() returns an order object — not a tuple.Test: Can a new team member predict what this function/button/endpoint does from its name alone? If not, rename it.
Every error MUST tell the user three things:
| Bad | Good |
|---|---|
| "Error 500" | "Failed to save your changes because the database is temporarily unavailable. Your changes are saved locally and will sync when the connection is restored." |
| "Invalid input" | "Email address must contain @ and a domain (e.g., [email protected])." |
| "Permission denied" | "You need the 'editor' role to modify this document. Contact your workspace admin to request access." |
| "Something went wrong" | "We couldn't load your dashboard because the analytics service is slow. Retrying in 5 seconds..." |
Never show raw exceptions, stack traces, or error codes to end users. Log them for developers; show human-readable messages to users.
Start simple. Reveal complexity only when needed.
| Layer | Content | When shown |
|---|---|---|
| 1. Essential | Core functionality, required inputs | Always |
| 2. Common | Frequently used options | On request or contextually |
| 3. Advanced | Power user features, edge case config | Behind "Advanced" or docs |
| 4. Expert | Internal tuning, debugging, raw access | Documentation only |
Users make mistakes. The system MUST make recovery easy:
"Are you sure?" dialogs are a last resort, not a design pattern. Better: make the action reversible.
Every user action MUST produce visible feedback:
| Action timing | Required feedback |
|---|---|
| <100ms | Immediate state change (no loader needed) |
| 100ms - 1s | Loading indicator (spinner, skeleton, progress) |
| 1s - 10s | Progress bar with estimate |
| >10s | Background processing with notification on completion |
No silent failures. If an action fails, the user MUST know — immediately and clearly.
No mystery states. The user should always be able to answer: "What is the system doing right now? What do I do next?"
Usability includes EVERYONE:
| Requirement | Implementation |
|---|---|
| Keyboard navigation | All interactive elements reachable via Tab, usable via Enter/Space |
| Screen reader support | Semantic HTML, ARIA labels, alt text for images |
| Color contrast | WCAG AA minimum (4.5:1 text, 3:1 large text) |
| No color-only indicators | Use icons, patterns, or text alongside color |
| Responsive design | Works on mobile through desktop |
| Focus management | Visible focus indicators, logical tab order |
Accessibility is not optional. It's a legal requirement in many jurisdictions and a moral one everywhere.
The entire system MUST use consistent patterns:
Before finalizing any design or plan, run the Usability Checklist:
If any item fails: redesign before proceeding to implementation.
As you write code:
Verify these as part of every code review:
If existing code violates these rules:
| Pattern | Problem | Fix |
|---|---|---|
| "Error: null" | User has no idea what happened | Structured error with action |
| Modals on modals | User trapped in dialog hell | Inline editing or single modal |
| Hidden functionality | Users can't find features | Progressive disclosure, not hiding |
| Jargon in UI | Users don't speak developer | Use domain language, not technical terms |
| Disabled buttons without explanation | User doesn't know why they can't proceed | Tooltip or inline text explaining the condition |
| Inconsistent terminology | "Save" vs "Submit" vs "Confirm" for same action | Pick one term, use it everywhere |
| Excuse | Reality |
|---|---|
| "Power users will figure it out" | Power users hate bad UX too. They just suffer silently. |
| "The docs explain it" | Nobody reads docs for something that should be intuitive. |
| "We'll improve UX in v2" | v2 UX debt is twice as expensive. Get it right now. |
| "It's technically correct" | Technically correct + unusable = useless. |
| "Accessibility is a nice-to-have" | It's a legal requirement and moral obligation. |
| "We're not designers" | Usability is engineering, not art. Follow the rules. |
npx claudepluginhub alo-exp/silver-bullet --plugin silver-bulletGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.