@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/ux-destructive-action-copy/SKILL.md

@@ -0,0 +1,152 @@
+# Destructive Action Copy
+
+> Destructive action copy — irreversibility warnings, undo availability, double-confirmation patterns, cooldown messaging
+
+## When to Use
+
+- Writing delete flows for records, files, repositories, accounts, or workspaces
+- Designing confirmation dialogs for irreversible state changes
+- Building account termination and data deletion flows
+- Creating bulk destructive operation warnings
+- Designing undo and grace period messaging for soft-deletions
+- Writing type-to-confirm patterns for highest-consequence actions
+- NOT for: routine confirmations where the action is easily reversible (use ux-confirmation-dialogs)
+- NOT for: error recovery flows where no deliberate destructive action was taken
+- NOT for: archive or hide actions that preserve data in a recoverable state
+
+## Instructions
+
+1. **State irreversibility explicitly if the action cannot be undone.** Users calibrate their caution based on whether they can recover from a mistake. "This cannot be undone" is not boilerplate -- it is a factual statement about the system's behavior that directly informs the user's decision. When an action is recoverable (soft delete with a 30-day window), say so explicitly: "You can restore this within 30 days." When an action is partially recoverable ("Your repositories will be transferred, but your account data will be deleted immediately"), name the boundary precisely. Never assume the user understands from context whether a destructive action is permanent -- state it plainly at the decision point, not in help documentation they will never read. GitHub's repository deletion dialog says "This action is permanent and cannot be undone." Stripe's subscription cancellation says "Your subscription will end at the end of your billing period -- no further charges."
+
+2. **Name exactly what will be destroyed -- including counts and downstream effects.** Vague destruction warnings undercount the consequences and leave users surprised after the fact. "Delete this workspace" is insufficient. "Delete 'Acme Corp' workspace and its 14 members, 230 projects, and 4,200 tasks -- all data will be permanently deleted" is complete. Linear's team deletion shows: "Deleting this team will permanently delete all issues (47), cycles (8), projects (3), and associated data. Members will lose access immediately." The count is dynamically generated from live data -- what will actually be destroyed is shown, not estimated. Downstream effects (members losing access, integrations disconnecting, billing stopping) are named explicitly so the user can evaluate the full scope of their decision before confirming.
+
+3. **Offer undo where the system technically supports it -- undo transforms dangerous into recoverable.** The single biggest UX improvement for destructive actions is adding a soft-delete grace period and advertising it prominently. "Moved to trash. Undo" in a toast message converts a catastrophic mistake into a three-second fix. The undo affordance must appear immediately, in the user's current view, with a clear action -- not buried in a settings menu or trash view that requires navigation. Google Drive's "Moved to trash" toast with "Undo" has set user expectations across the industry; users now expect undo to exist and are disproportionately frustrated when it does not. If undo is technically possible, implement it and lead the confirmation dialog with that information: "You can undo this from your trash within 30 days." This framing shifts the emotional experience from irreversible loss to managed risk.
+
+4. **Type-to-confirm patterns for highest-consequence actions -- require the exact resource name, not a generic word.** When the consequence of a mistake is catastrophic and irreversible (delete a production database, terminate an organization account, destroy all billing history), a click-to-confirm dialog is insufficient friction. Require the user to type the name of the specific resource being destroyed. This serves two purposes: it ensures the user is present and deliberate (not clicking through a dialog), and it names the specific object one more time, making it impossible to accidentally delete the wrong resource in a list. GitHub requires typing the full repository name: "To confirm, type the name of the repository: [repo-name]." Never require typing a generic word like "DELETE" or "CONFIRM" -- the generic word adds friction without adding specificity, and users memorize the required string ("just type DELETE") rather than engaging with the consequence.
+
+5. **Cooldown copy for async or scheduled deletions -- make the window and cancellation path explicit.** When deletion is not immediate (account deletion with a 30-day recovery period, scheduled data purge, export-then-delete workflow), the copy must communicate three things: when the deletion takes effect, what is accessible during the window, and how to cancel. Google's account deletion page shows: "Your account will be deleted in 30 days. During this time you can sign in to recover your account. After 30 days, your data will be permanently deleted and cannot be recovered." Each sentence answers a different question the user will have. The cancellation path ("sign in to recover") is named as a concrete action, not a vague possibility -- users who discover the grace period after the fact need to know exactly what to do without searching for documentation.
+
+6. **Warn before -- the warning must appear before the point of no return, not after.** A post-deletion "Your account has been deleted" confirmation screen is not a warning -- it is a receipt. The warning belongs at the decision point: the confirmation dialog, the settings page with the delete button, or the preview step in a multi-step deletion flow. For multi-step destructive workflows, warnings should escalate: a mild warning at the initiation step ("This will permanently delete your account"), a stronger warning at the confirmation step (with type-to-confirm and a list of what will be lost), and a final summary before the irreversible action executes. Stripe's subscription cancellation flow shows the plan end date, the data retention period, and a summary of what will be lost at each step -- building a complete picture before any irreversible state change occurs.
+
+7. **The destructive button text is the specific verb -- not a euphemism or a generic positive.** "Remove," "End," "Clear," "Close," "Deactivate" are euphemisms for "Delete," "Terminate," "Purge," "Cancel," "Disable." Euphemisms reduce cognitive engagement with the consequences of the action. When a user reads "Delete" on a red button in a deletion confirmation dialog, the word's meaning activates the appropriate level of caution; "Remove" activates a softer mental model -- something like removing a sticker, not destroying data. Use "Delete" for permanent deletion, "Cancel" for subscription termination (not "End plan"), "Terminate" for forced account closure, "Purge" for bulk data deletion with no recovery. The button text must match the severity of the action, because the button text is the last thing the user reads before the point of no return.
+
+## Details
+
+### Destructive Action Severity Scale
+
+Not all destructive actions warrant the same level of friction. Apply friction proportional to consequence:
+
+| Severity | Action Type                         | Confirmation Pattern              | Example                             |
+| -------- | ----------------------------------- | --------------------------------- | ----------------------------------- |
+| Low      | Reversible delete                   | Toast with Undo (5-30 seconds)    | Move to trash, archive              |
+| Medium   | Single-record delete                | Click-to-confirm dialog           | Delete a comment, remove a member   |
+| High     | Multi-record or team-visible delete | Confirm dialog + consequence list | Delete a project, remove a team     |
+| Critical | Irreversible, organization-wide     | Type-to-confirm + 30-day grace    | Delete workspace, terminate account |
+
+The scale should be established as a design system convention so that the same action type receives the same friction pattern throughout the product. A "delete comment" confirmation should not require typing the comment text; a "delete organization" confirmation should never be a single-click. Establish the scale in the design system token documentation and link to it from every destructive action pattern.
+
+### Type-to-Confirm Copy Pattern
+
+The type-to-confirm pattern has three required copy elements:
+
+1. **Instruction line:** "To confirm, type the name of the [resource type] below:" -- names what the user must type and why.
+2. **Placeholder in the input field:** The exact string the user must match, shown as placeholder text: "acme-corp-workspace"
+3. **Button state:** The destructive button should be disabled until the typed string matches exactly, then enable. Do not show an error for mismatch -- just keep the button disabled. GitHub's pattern is precise: the input has the repo name as placeholder, the "Delete this repository" button enables only on exact match, and the match is case-sensitive.
+
+A fourth optional element: "This cannot be undone" as a final reminder beneath the input field, immediately before the button.
+
+### Review Checklist
+
+Use this checklist before shipping or reviewing any destructive action flow:
+
+| Check                   | Criteria                                               | Pass Condition                                                                    |
+| ----------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| Reversibility statement | Action is labeled recoverable or permanent             | "This cannot be undone" or "Restore within 30 days" appears at the decision point |
+| Consequence specificity | Dialog names the object and downstream effects         | Includes object name and count of affected records/members                        |
+| Severity classification | Action is classified on the severity scale             | Correct confirmation pattern applied (toast / click / type-to-confirm)            |
+| Type-to-confirm         | Critical actions use exact resource name               | Generic "DELETE" strings are not accepted; specific resource name required        |
+| Undo availability       | Soft-delete systems show inline undo                   | Toast with "Undo" appears immediately; undo is not buried in trash settings       |
+| Button text             | Destructive button uses specific strong verb           | No euphemisms ("Remove," "End," "Clear") for permanent actions                    |
+| Cooldown copy           | Scheduled deletions state window and cancellation path | Exact number of days and specific action to cancel are named                      |
+| Warning placement       | Warnings appear before point of no return              | No post-deletion "warnings" that are actually receipts                            |
+
+### Anti-Patterns
+
+1. **The Euphemism.** Destructive buttons labeled with soft verbs that understate the action's severity. Before: "Remove account," "End subscription," "Clear data." After: "Delete account," "Cancel subscription," "Permanently delete all data." The test: would a user who glances at the button for one second understand that this action destroys something permanently? If the verb could describe an easily reversible action (removing a sticker, ending a call, clearing a search field), it is a euphemism. Euphemisms are especially harmful on mobile where confirmation dialogs are smaller and users are more likely to tap through quickly without reading carefully.
+
+2. **The Generic Warning.** Confirmation dialogs that use boilerplate copy not specific to the action being confirmed. Before: "Are you sure you want to delete this? This action cannot be undone." After: "Delete 'Q4 Marketing Campaign' and its 12 linked assets? This will remove the campaign from all reports and revoke access for 3 collaborators. This cannot be undone." The generic warning is written once and reused everywhere; the specific warning is generated from live data about the specific object being destroyed. Generic warnings normalize the confirmation pattern -- users who see the same dialog for deleting a comment as for deleting a workspace stop reading it and click through on reflex.
+
+3. **The Hidden Undo.** Soft-delete systems where the undo affordance is buried in a settings menu or requires navigating to a trash view, rather than appearing as an inline action immediately after the deletion. Before: Item is deleted, no toast, undo is available via Settings > Trash > Restore. After: Item is deleted, toast appears: "'Q4 Campaign' deleted. Undo -- or view Trash." The undo link must appear immediately in the user's current context, not require a navigation. A 5-second undo toast is infinitely more usable than a trash bin that requires three clicks. When users discover the hidden undo only after it has expired, the experience is worse than if undo never existed -- because the user now knows they were one navigation away from recovery.
+
+4. **The Surprise Deletion.** A destructive action with no warning at the point of initiation -- the user clicks "Delete" expecting a confirmation dialog and instead the item is immediately gone. Before: "Delete" button in a row action menu that deletes the record immediately. After: "Delete" triggers a confirmation dialog. The rule: any action that cannot be undone within 5 seconds must require confirmation. Any action that affects more than the single item the user interacted with must name the scope of destruction in the confirmation. Surprise deletions are the primary cause of "I accidentally deleted my entire project" support tickets and permanent user churn from SaaS products.
+
+### Real-World Examples
+
+**GitHub repository deletion.** GitHub's repository deletion is the canonical example of a type-to-confirm pattern. The flow: navigate to Settings > Danger Zone > Delete this repository > dialog appears with full consequence list ("This will permanently delete the [repo-name] repository, wiki, issues, comments, packages, secrets, workflow runs, and all other associated repository data") + type-to-confirm ("To confirm, type the name of the repository: [repo-name]") + red "Delete this repository" button. The 30-day repository restore window was added in 2019 and is advertised in GitHub Docs, but not in the deletion dialog itself -- a notable gap that creates a missed opportunity to reduce deletion anxiety for users who might restore rather than delete. The type-to-confirm requires the exact repo name including organization prefix for organization repositories: "acme-corp/harness-engineering."
+
+**Stripe subscription cancellation with data retention notice.** Stripe's subscription cancellation flow is designed to reduce regret, not to prevent cancellation. The flow is straightforward but information-dense: it shows the plan end date (end of current billing period), confirms that all data is retained after cancellation (the account does not close, only the subscription ends), and offers a plan downgrade as an alternative. The key copy: "Your [Plan Name] subscription will end on [Date]. After this date, you'll be moved to the free plan. Your data will be preserved." This phrasing specifically addresses the fear that cancellation equals data deletion, which is the primary source of cancellation anxiety in SaaS products -- Stripe's copy engineering decision is to defuse that fear explicitly rather than hoping users infer it.
+
+**Google account deletion 30-day grace period.** Google's account deletion flow is one of the most consequential destructive flows in consumer software. The multi-step flow includes: a list of all Google services and data that will be deleted, a checkbox acknowledging each major data category, a warning about the 20-day window after which data becomes unrecoverable, and confirmation that some data (purchased content, shared documents) may be retained differently. The grace period copy is explicit: "After deleting your account, you have a 20-day window to sign back in and cancel the deletion." Google pre-downloads all user data via Takeout before the deletion flow reaches the confirmation step -- the copy guides users through this prerequisite, treating data preservation as a first-class concern rather than an afterthought.
+
+**Notion workspace deletion flow.** Notion's workspace deletion requires navigating to Settings > [Workspace name] > Delete workspace. The confirmation dialog names the workspace and shows a count of all pages, databases, and members. The type-to-confirm requires the exact workspace name. What makes Notion's flow distinctive is the pre-deletion export prompt: before the type-to-confirm step, Notion surfaces "Export workspace content" as a recommended action with a direct link. This is copy that reduces regret -- giving the user one more opportunity to preserve their data before the irreversible action. The export prompt does not block deletion, but its placement immediately before the type-to-confirm step is deliberate, serving as a final "are you really sure?" moment without requiring an additional confirmation click.
+
+### Copy Formulas Quick Reference
+
+These are fill-in-the-blank templates for the most common destructive action copy patterns:
+
+- **Irreversibility statement:** `This action is permanent and cannot be undone.`
+- **Soft-delete statement:** `You can restore this within [N] days from [Trash / Settings > Deleted items].`
+- **Consequence list item:** `[N] [records / members / projects] will be permanently deleted.`
+- **Downstream effect:** `[Connected service] will lose access immediately.`
+- **Type-to-confirm instruction:** `To confirm, type the name of the [resource type] below:`
+- **Type-to-confirm placeholder:** `[exact-resource-name]`
+- **Post-deletion toast:** `'[Name]' deleted. Undo`
+- **Grace period copy:** `Your [resource] will be deleted in [N] days. Sign in before [Date] to cancel.`
+- **Cooldown cancellation:** `To cancel deletion, [specific action] before [Date / timeframe].`
+- **Destructive button -- delete:** `Delete [resource name]`
+- **Destructive button -- terminate:** `Terminate account`
+- **Destructive button -- purge:** `Permanently delete all data`
+
+## Source
+
+- NNGroup -- "Confirmation Dialog Boxes," https://www.nngroup.com/articles/confirmation-dialog/
+- NNGroup -- "Preventing User Errors: Avoiding Unconscious Slips," https://www.nngroup.com/articles/slips/
+- Apple Human Interface Guidelines -- Alerts, https://developer.apple.com/design/human-interface-guidelines/alerts
+- Laubheimer, P. -- "Checkboxes vs. Toggles in Mobile Design," NNGroup (2015)
+- GitHub -- Deletion and data recovery documentation, https://docs.github.com/en/repositories/creating-and-managing-repositories/deleting-a-repository
+- Yifrah, K. -- _Microcopy: The Complete Guide_ (2017), Chapter 9: Errors, Warnings, and Destructive Actions
+
+## Process
+
+1. **Classify the destructive action on the severity scale** (low / medium / high / critical). The severity determines the confirmation pattern -- do not apply the same friction to all destructive actions. Write the severity classification into the component spec so that future developers do not have to re-derive it for similar actions. Review the severity classification with a product manager who can confirm the actual recoverability of the data before the copy is written.
+
+2. **For medium and high severity actions:** Write the confirmation dialog with a specific title (naming the object), a consequence list (what exactly will be deleted, with live counts from the API), reversibility statement (permanent or soft-delete with window length), and a destructive verb button. Ensure the object name and counts are dynamically generated -- hardcoded counts become wrong the moment the data changes.
+
+3. **For critical severity actions:** Add the type-to-confirm pattern with exact instruction copy ("To confirm, type the name of the [resource type]:"), placeholder showing the required string, and button-disabled-until-match behavior. Confirm with engineering that the match is case-sensitive and that the exact required string is displayed in the dialog. Test the disabled/enabled button transition manually before shipping.
+
+4. **If the system supports soft-delete or a grace period:** Write the post-deletion toast with an inline undo action ("'[Name]' deleted. Undo"), and the grace period copy naming the exact window length and the specific action to cancel the deletion. Confirm with engineering what the exact window length is in days and whether the window is from deletion time or end of day -- this specificity matters when users are near the boundary.
+
+5. **Audit all destructive button labels across the product for euphemisms.** Build a list of every destructive action button in the product and classify each verb. Replace "Remove," "End," "Clear," "Close," or "Deactivate" with the appropriate strong verb ("Delete," "Cancel," "Purge," "Terminate," "Disable") that matches the severity and permanent nature of the action. Document the verb vocabulary in the design system so that new destructive actions default to the correct verb.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Irreversible actions explicitly state "This cannot be undone" or equivalent at the decision point -- no destructive action is presented as reversible when it is not.
+- Confirmation dialogs name the specific object being destroyed and include a dynamically generated count of affected downstream data (members, records, assets).
+- Type-to-confirm is used for all critical-severity actions (account deletion, workspace deletion, production data purge) and requires the exact resource name, not a generic confirmation string.
+- Soft-delete and grace period copy names the exact window length in days and the specific action the user must take to cancel within the window.
+- All destructive buttons use strong, specific verbs ("Delete," "Cancel," "Terminate," "Purge") -- no euphemisms like "Remove," "End," or "Clear" for permanent actions.
+- Post-deletion undo toasts appear immediately in the user's current view and provide an inline undo action -- undo is not reachable only via a separate trash or settings menu.
+- Warning copy appears at the decision point before the irreversible action, not on a confirmation screen after the action has already occurred.
+
+## Mobile and Edge-Case Considerations
+
+On mobile, confirmation dialogs for destructive actions must be designed with the additional constraint that tap targets are small and users frequently dismiss dialogs by tapping outside them. A destructive confirmation dialog on iOS or Android should use the platform's native alert pattern (system modal) rather than a custom bottom sheet that can be swiped away. The type-to-confirm pattern is high-friction on mobile keyboards -- on mobile, reserve it only for the most critical actions and consider an alternative like a 5-second countdown button ("Hold to delete") for high-severity but not critical actions.
+
+Bulk destructive actions over large datasets require additional copy: when deleting hundreds or thousands of items, show a progress indicator with copy like "Deleting 1,847 records... Do not close this window." If the deletion is async and continues in the background, say so: "Deletion in progress. You'll receive an email when complete." Users who initiate large bulk deletions and then see no feedback will refresh the page, navigate away, and potentially trigger the operation twice.
+
+For actions that require a grace period email confirmation (some GDPR-compliant deletion flows send an email with a confirmation link before deletion begins), the in-product copy must set the expectation: "Check your email at user@example.com for a confirmation link. Deletion begins after you confirm." Name the email address so the user knows which inbox to check, and set the expectation that the confirmation link expires: "The link expires in 24 hours."

package/dist/agents/skills/gemini-cli/ux-destructive-action-copy/skill.yaml

@@ -0,0 +1,34 @@
+name: ux-destructive-action-copy
+version: "1.0.0"
+description: Destructive action copy — irreversibility warnings, undo availability, double-confirmation patterns, cooldown messaging
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-confirmation-dialogs
+  - ux-button-cta-copy
+  - ux-microcopy-principles
+stack_signals: []
+keywords:
+  - destructive-action
+  - irreversibility
+  - undo
+  - double-confirmation
+  - data-loss
+  - warning-copy
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ux-empty-states/SKILL.md

@@ -0,0 +1,155 @@
+# Empty States
+
+> Empty states — first-use, user-cleared, and no-results patterns that motivate action, set expectations, and turn blank screens into onramps
+
+## When to Use
+
+- Designing first-use screens when a user has no data yet (fresh accounts, new workspaces)
+- Writing zero-results messages for search or filter operations
+- Creating user-cleared states after all items are completed, deleted, or removed
+- Writing error-state empty screens (failed to load content, permission denied)
+- Building empty states for data tables, dashboards, timelines, and activity feeds
+- NOT for: loading states before data arrives (see ux-loading-states)
+- NOT for: onboarding flows and welcome sequences spanning multiple screens (see ux-onboarding-copy)
+- NOT for: error messages for system failures (see ux-error-messages)
+
+## Instructions
+
+1. **Classify the empty state type before writing any copy.** First-use, user-cleared, no-results, and error-empty each need different copy, tone, and CTA. First-use motivates: the user is new and needs to understand the value of filling the space. User-cleared celebrates: the user accomplished something (inbox zero, completed all tasks). No-results guides: the user searched and found nothing, and needs help adjusting. Error-empty explains: something failed to load and the user needs a recovery path. Writing the wrong type of copy — motivational text for a no-results screen — creates confusion and erodes trust. A "Create your first project!" message on a filtered no-results screen actively misleads users who know their projects exist.
+
+2. **Always include exactly one clear CTA.** Notion's empty page: "Press '/' for commands." GitHub's empty repository: "Create a new file or upload an existing file." The CTA must be a specific action, not a generic invitation. Multiple CTAs on an empty state create decision paralysis. If there are multiple paths forward (create, import, invite), choose the single most common one as the primary CTA and surface others as secondary text or links beneath the primary button. The hierarchy of options must be unmistakable — one primary, at most two secondary, and nothing that creates a fork without guidance.
+
+3. **Show the value of filling the empty state, not just how to fill it.** "Track your team's progress in real time" is motivating. "Click 'New Project' to create a project" is mechanical. The motivational framing answers the implicit user question: "Why would I bother?" Linear's empty issues state: "No issues. Ship fast." — the absence of issues is reframed as an achievement, and the CTA is implied by the feature's purpose. Value-first copy converts passive first-time users into active ones. Show the outcome, then the action — not the action alone. The user needs to believe the effort of creating content is worth it.
+
+4. **For no-results states, suggest specific recovery actions.** "No results for 'reciepe'" should be followed by a spelling suggestion ("Did you mean 'recipe'?"), a filter relaxation option ("Try removing the 'closed' filter"), or a browse alternative ("Browse all issues"). Never show just "No results found" without at least one recovery path. Linear's no-results state suggests broadening search terms and provides a one-click option to clear all filters. GitHub's code search suggests checking the search syntax or expanding to all branches. The recovery path must match the type of search — structured search needs filter controls, full-text search needs spelling help.
+
+5. **Keep empty state copy under 3 sentences total.** The screen is already visually sparse — a paragraph of text makes it feel heavier, not more helpful. A headline (one phrase or question), a brief explanation (one sentence, optional), and a CTA (one button or link) is the maximum. Slack's empty channel state: "This is the very beginning of the #general channel." — one sentence, historically resonant, leaves room for the first message. The brevity of the copy matches the openness of the space. If you need more than three sentences, you are writing documentation, not an empty state.
+
+6. **Use illustrations judiciously — copy must carry the message independently.** An illustration without actionable text is decoration. The empty state must work without the illustration in case it fails to load, is below the fold, or the user is using a screen reader. Write the copy as if there is no illustration. If the illustration adds meaning, reference it implicitly. Notion's empty page illustration of a hand holding a pencil works because the text explains the action — the illustration reinforces rather than replaces the message. Test the empty state with illustrations hidden — if it still communicates, the copy is doing its job.
+
+7. **Detect first-use versus returning-user context and serve different copy.** First-use empty states need motivational context because the user does not yet understand the product. Returning-user empty states — after the user has deleted all content or cleared a queue — need brevity and respect, because the user already understands the product. "All caught up." is sufficient for an inbox-zero state for an experienced user; the same screen shown to a new user needs the motivational context. When detection is not possible, default to returning-user brevity rather than first-use verbosity — experienced users are more likely to hit empty states repeatedly.
+
+8. **Error-empty states must distinguish between recoverable and unrecoverable failures.** "Couldn't load your projects. Try again." is recoverable — user can retry. "You don't have permission to view this content. Contact your workspace admin." is escalation required — user cannot self-resolve. The error-empty state must name the failure type and provide the appropriate recovery path: retry for transient errors, contact support or admin for permission issues, status page for system outages. Never show an empty state illustration with "No content here" when the actual cause is a permissions failure — the mismatch between visual tone (empty, neutral) and reality (blocked, error) misleads users.
+
+## Details
+
+### Empty State Type Matrix
+
+Selecting the wrong type creates the wrong emotional register. A celebratory tone on an error-empty screen is jarring. A motivational tone on a no-results screen is irrelevant. Always classify before writing.
+
+| Type         | User Goal           | Tone        | CTA Pattern              | Example                              |
+| ------------ | ------------------- | ----------- | ------------------------ | ------------------------------------ |
+| First-use    | Understand value    | Inviting    | Verb-noun primary action | "Create your first project"          |
+| User-cleared | Confirm completion  | Celebratory | Optional next challenge  | "Inbox zero. Enjoy the peace."       |
+| No-results   | Find alternatives   | Helpful     | Specific recovery action | "No results. Try removing filters."  |
+| Error-empty  | Recover or escalate | Empathetic  | Retry or support link    | "Couldn't load projects. Try again." |
+
+### First-Use vs Returning-User Empty States
+
+**First-use empty state:** The user has never created content. Emphasize starting value and low risk. Stripe's empty transactions table for new merchants: "No transactions yet. Create a payment link to start accepting payments." The assumption is the user is unfamiliar with the workflow. Surface the "aha moment" — show what this space will look like when populated, not just how to fill it.
+
+**Returning-user empty state:** The user deleted all content or cleared a queue. They are familiar with the product. Skip the explanation and go straight to the action. "All caught up. Create a new issue." or "No open invoices." For returning users, brevity signals respect for their expertise. A returning user who has deleted all their projects does not need to be told what a project is.
+
+When possible, detect first-use vs returning-user status to serve the appropriate version. If not detectable, default to returning-user brevity.
+
+### No-Results Recovery Patterns
+
+No-results states should offer at minimum one of these recovery paths, matched to the search type:
+
+- **Spelling suggestion:** "Did you mean 'authentication'?" with a clickable link to that search.
+- **Filter relaxation:** "Showing results in 'Engineering' only. Search all workspaces." with a one-click option.
+- **Scope expansion:** "No results in this project. Search across all projects."
+- **Browse alternative:** "No results for 'API documentation'. Browse all docs."
+- **Clear all:** A single button to reset all filters and return to the full list.
+- **Query tips:** For structured search (code, SQL, commands), show syntax help inline.
+
+Linear combines filter relaxation with browse alternatives. GitHub's search provides detailed syntax help when no results are found. The goal is to never leave the user stranded with only "No results" and a back button.
+
+### Copy Length by Empty State Location
+
+Different screens have different density tolerances for empty state copy:
+
+| Screen Type         | Headline          | Body               | CTA                 |
+| ------------------- | ----------------- | ------------------ | ------------------- |
+| Full page           | 4-8 words         | 1-2 sentences      | 1 primary button    |
+| Panel / sidebar     | 3-6 words         | 1 sentence or none | 1 link or button    |
+| Data table row area | 4-8 words         | 1 sentence or none | 1 inline link       |
+| Modal / dialog      | 3-6 words         | 1 sentence or none | 1 primary + 1 close |
+| Card / widget       | 2-4 words or icon | None               | 1 link              |
+
+### Anti-Patterns
+
+1. **The Barren Wasteland.** A completely blank screen with no guidance, no illustration, no text, and no CTA. The user stares at white space with no understanding of what the space is for or what to do next. This most commonly occurs in developer-first products where the empty state was never designed. The fix: every empty state requires at minimum a headline and a CTA — a one-sentence explanation of what the user can create or do in this space is the minimum viable empty state.
+
+2. **The Instruction Manual.** A paragraph or more of explanation about how to use the feature in the empty state, overwhelming the user at the moment they need the most encouragement. "Welcome to Projects! Projects help you organize your work into containers. You can add tasks, set deadlines, invite team members, and track progress. To get started, click the 'New Project' button in the top right corner..." This is documentation, not an empty state. Condense to one phrase, one optional sentence, one CTA.
+
+3. **The Sad Illustration.** A decorative illustration (an empty box, a sad robot, a blank page with question marks) with no actionable text, no CTA, and no explanation. The illustration communicates "nothing is here" visually but gives the user nowhere to go. Empty state illustrations should always be accompanied by text that explains what should be here and how to add it. An illustration without text is visual wallpaper — it aestheticizes the problem without solving it.
+
+4. **The Wrong Type.** Using first-use motivational copy for a no-results state, or user-cleared celebratory copy for an error-empty state. "Create your first project!" shown when all projects are filtered by "Archived" actively misleads the user into thinking they have no projects. The empty state type must match the actual situation. If the product cannot detect the difference between first-use and filtered-empty, default to neutral language that works for both: "No projects to show" with filter controls visible is better than "Create your first project" when projects may exist but are hidden.
+
+### Real-World Examples
+
+**Notion's Blank Page Experience.** Notion's empty page state uses a single instructional line: "Press '/' for commands" with a secondary line "Start writing, or drag files here." The minimalism matches the product's philosophy that a blank page is potential, not a problem. The hint teaches the primary interaction model (the slash command) in context. Notion removes the hint after the user has used it a few times, transitioning to true blank-slate for experienced users. This adaptive behavior — showing motivation to new users, then getting out of the way — is the ideal empty state lifecycle.
+
+**GitHub's Empty Repository Setup.** GitHub's empty repository page is the gold standard for first-use empty states in developer tools. It provides the exact git commands to initialize and push a new repository, copy buttons for each command block, and multiple paths (new file, README, .gitignore, upload files). The technical nature of the content means more text is appropriate here than in most empty states. GitHub trusts its users enough to show them commands rather than hiding complexity behind a "Get started" button. The empty state teaches the workflow rather than abstracting it.
+
+**Slack's Empty Channel State.** When a channel is first created, Slack shows: "This is the very beginning of the #[channel-name] channel." This simple message sets context (this is the start), establishes ownership (this is your channel), and creates a sense of occasion. No CTA is needed — the user knows what to do (send a message). The message disappears once the first message is sent — it is contextually relevant only at the moment of creation.
+
+**Linear's No-Results Search.** Linear's search returns "No results for '[term]'" with two recovery paths: clear the search and see all results, or search across all teams. The zero-results state also surfaces keyboard shortcuts to refine the search. Linear avoids suggestions and spelling corrections because its search is structured (searching issues, projects, members) rather than full-text — the recovery paths it offers match its actual capabilities rather than importing patterns from full-text search that would not work here.
+
+## Source
+
+- NNGroup — "The Power of Empty States" (2017), https://www.nngroup.com/articles/empty-state-mobile-app-nice-to-have/
+- Google Material Design — Empty states guidance, https://m3.material.io/foundations/layout/understanding-layout/parts-of-a-layout
+- Invision — "How to Design Empty States," https://www.invisionapp.com/inside-design/empty-state-design/
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), empty state and zero-data patterns
+- Hulick, S. — _The Elements of User Onboarding_ (2013), first-use and value-first patterns
+
+### Empty States in Feature-Gated Contexts
+
+When an empty state is caused by a plan or permissions limitation — not the absence of data — the copy must address the actual cause:
+
+**Plan gate empty state:** "Analytics are available on the Pro plan. Upgrade to see your traffic data →." The copy names what is missing (analytics), explains why (Pro plan), and offers the next step (upgrade). Do not show a generic empty state illustration with "No data yet" — the user may have data, they just cannot see it. Misrepresenting a plan gate as an absence of data confuses users and erodes trust.
+
+**Permission gate empty state:** "You don't have access to this workspace. Contact your admin to request access." The copy distinguishes between "no content exists" and "you can't see the content that exists" — a critical distinction for user mental models. GitHub shows "You need to be a collaborator to view this repository" — clear, accurate, with an implicit next step (become a collaborator).
+
+The rule: always tell the user why the space is empty, not just that it is empty. The reason determines the recovery path — creation, upgrade, or permission request.
+
+## Process
+
+1. Classify the empty state as first-use, user-cleared, no-results, or error-empty — confirm the classification matches the actual user situation.
+2. Write a headline of 3-8 words that names the type of content that belongs here and its value.
+3. Add one optional sentence of context if the headline alone is insufficient.
+4. Write a single specific CTA (verb-noun) as a button or link.
+5. For no-results states, add at least one recovery path: spelling suggestion, filter relaxation, or scope expansion.
+
+### Empty State Copy Audit Checklist
+
+Before shipping an empty state, verify each item:
+
+| Check                                               | Pass Criteria                                              |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| Type classified                                     | First-use, user-cleared, no-results, or error-empty        |
+| Copy works without illustration                     | Message is comprehensible with image removed               |
+| Exactly one primary CTA                             | Single specific verb-noun action, not two or more          |
+| Under 3 sentences total                             | Headline + optional body + CTA                             |
+| No results state has a recovery path                | Filter clear, scope expand, or spelling suggestion present |
+| Error-empty distinguishes recoverable vs escalation | "Try again" vs "Contact admin" based on error type         |
+| Value shown, not just instructions                  | Answers "why bother?" not just "how to"                    |
+| First-use vs returning-user context respected       | Motivational for new, brief for returning                  |
+
+A blank or generic empty state is a missed opportunity in every product. Empty states occur most often when users are new (high value moment) or when search fails (high frustration moment) — both moments where copy quality has outsized impact on whether users continue or abandon.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Every empty state is classified as one of the four types and uses the appropriate tone and CTA pattern.
+- Empty state copy is 3 sentences or fewer, including a single specific CTA.
+- No-results states include at least one recovery path (spelling correction, filter relaxation, or browse alternative).
+- First-use empty states lead with the value of the content, not just instructions for how to create it.
+- Empty state copy is independently comprehensible without relying on an illustration.
+- Error-empty states distinguish between recoverable failures (retry) and unrecoverable failures (contact admin / support).

package/dist/agents/skills/gemini-cli/ux-empty-states/skill.yaml

@@ -0,0 +1,36 @@
+name: ux-empty-states
+version: "1.0.0"
+description: Empty states — first-use, user-cleared, and no-results patterns that motivate action, set expectations, and turn blank screens into onramps
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-onboarding-copy
+  - ux-writing-for-scanning
+  - design-empty-error-states
+  - design-loading-patterns
+stack_signals: []
+keywords:
+  - empty-states
+  - first-use
+  - zero-data
+  - no-results
+  - onboarding
+  - blank-slate
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ux-error-messages/SKILL.md

@@ -0,0 +1,159 @@
+# Error Messages
+
+> Error messages — what went wrong, why it matters, how to fix it, the three-part error pattern for clear, actionable error communication
+
+## When to Use
+
+- Writing form validation error messages (inline, summary banner, or toast)
+- Composing system error messages (500 errors, timeouts, connectivity failures)
+- Creating API error responses that surface to end users
+- Writing permission-denied or authorization error text
+- Handling field-level and page-level validation across complex forms
+- NOT for: error logging or developer-facing error messages (stack traces, debug output)
+- NOT for: empty state copy shown when no content exists (see ux-empty-states)
+- NOT for: severity tier selection and escalation patterns (see ux-error-severity)
+
+## Instructions
+
+1. **Use the three-part pattern: what went wrong, why, how to fix it.** Every useful error message answers three questions: What failed? Why did it fail? What should the user do now? Stripe's payment decline: "Your card was declined. The issuing bank did not approve the transaction. Try a different payment method or contact your bank." Each clause serves one of the three purposes. A message with only "Card declined" leaves users stranded. A message with all three parts gives them a path forward. For system errors where the cause is unknown, omit the "why" rather than guessing — "We couldn't save your changes. Try again in a few minutes" is honest and actionable even without a known cause.
+
+2. **Place errors inline next to the field that caused them.** Error messages must appear in the same visual zone as the problem. GitHub highlights the specific field in red with the error message directly below it. A summary banner ("3 fields have errors") without inline messages requires the user to hunt for problems. Use both: inline messages for each field plus a page-level summary that links to each field, especially on long forms. Never display only a top-of-page summary for field-specific errors — the user should not have to scroll from the top banner back down to the field to understand what needs fixing.
+
+3. **Write errors in plain language — never expose technical codes or stack traces.** "Something went wrong" is better than "Error 500: Internal Server Exception" but "We couldn't save your changes. Try again in a few minutes." is better than both. Users do not understand HTTP codes, database exceptions, or stack traces. Translating technical failures into human language is the error writer's primary job. Notion translates sync conflicts: "Someone else edited this page. We've saved both versions — choose which to keep." No mention of merge conflicts or version hashes. Every technical error should be caught at the UI layer and replaced with a human sentence.
+
+4. **Use the same voice as the rest of the product — errors are not exempt from tone guidelines.** Slack's error messages maintain conversational tone even when things break: "Hmm, we can't reach our servers. Check your connection." Stripe maintains professional directness: "Your account is currently under review." Error states are the product's worst moment — a tonal mismatch makes them worse. If the product uses "you" and contractions elsewhere, use them in errors too. Reserve formal, impersonal language only if the product's baseline voice is formal and impersonal. An error that sounds robotic in a conversational product signals that the error was never reviewed by a writer.
+
+5. **Tell the user what to do next — every error must have a recovery path.** If user action can fix the error, name that action specifically. If no user action can fix it, say when the team is investigating, provide a status page link, or state when to retry. "Our servers are down. Check status.stripe.com for updates." is better than "Service unavailable." GitHub provides a link to their status page from every server error. Never leave the user with a problem and no path forward — even "Contact support" or "Try again later" is a recovery path. A dead-end error message is a product failure, not just a writing failure.
+
+6. **Do not blame the user.** Attribute the problem to the input or the system, never to the person. "That password is too short" not "You entered an invalid password." "This email is already registered" not "You already have an account." "The file is too large" not "You uploaded a file that's too big." Passive attribution to the object ("the file," "that password") is gentler than active attribution to the user ("you uploaded," "you entered"). Linear: "This name is already taken" not "You chose a name that's already in use." The user is already frustrated by the error; do not layer on fault attribution.
+
+7. **Be specific about constraints before and after errors occur.** "Password must be at least 8 characters, include one uppercase letter and one number" — show this as helper text before errors, and reference the specific unmet constraint in the error: "Password needs at least one number." Stripe shows the exact card requirement that was not met. Specificity eliminates the guessing game of "what does 'invalid password' actually mean?" and gives users actionable information they can use immediately to fix the issue. Vague errors like "Invalid input" require the user to guess what specifically is wrong.
+
+8. **Differentiate between field-level and page-level errors with distinct patterns.** Field-level messages are brief and inline: "Email address is required." Page-level messages describe the aggregate: "2 fields need your attention before continuing." For forms with many fields, a sticky page-level banner that links to each error field saves users from scrolling to find problems. Shopify's checkout shows a count-and-anchor pattern: "Please fix 2 errors below" with anchor links to each field. Both levels serve different navigation needs — page-level for orientation, field-level for resolution.
+
+## Details
+
+### Error Message Anatomy
+
+The three-part error structure maps directly to user cognitive needs:
+
+| Part       | Question Answered | Example                                      | Required?  |
+| ---------- | ----------------- | -------------------------------------------- | ---------- |
+| What       | What failed?      | "Your card was declined."                    | Always     |
+| Why        | What caused it?   | "The issuing bank did not approve."          | When known |
+| How to fix | What to do next   | "Try a different card or contact your bank." | Always     |
+
+For user-caused errors (form validation), the "why" is usually the constraint: "Password must include a number." For system errors, the "why" is the cause when known ("Our servers are temporarily unavailable") or omitted when not. The "how to fix" must always be present unless nothing can be done, in which case offer a status path ("Check status.stripe.com").
+
+### Error Placement Decision Matrix
+
+Selecting the wrong placement undermines the error's effectiveness. A transient network error in a blocking modal is disproportionate. A session expiration in a toast that auto-dismisses is a security and usability failure.
+
+| Error Type               | Placement            | Persistence     | Character Limit       |
+| ------------------------ | -------------------- | --------------- | --------------------- |
+| Field validation         | Inline, below field  | Until corrected | 1-2 short sentences   |
+| Multi-field form error   | Page banner + inline | Until corrected | Count + links to each |
+| System error (transient) | Toast / snackbar     | 5-8 seconds     | 120 characters        |
+| System error (blocking)  | Modal dialog         | Until dismissed | 2-3 sentences         |
+| Inline save failure      | Inline near trigger  | Until resolved  | 1 sentence + action   |
+
+### Error Tone Calibration by Error Category
+
+Error tone should match severity and the product's baseline voice:
+
+- **Field validation:** Calm, instructional, non-alarming. "Email address is required." Present tense, no exclamation.
+- **User mistake (recoverable):** Direct but gentle. "This email is already registered. Try logging in instead."
+- **System error (transient):** Empathetic, explains situation. "We're having trouble connecting. We'll keep trying."
+- **System error (persistent):** Direct with status path. "Our service is unavailable. Check status.stripe.com."
+- **Destructive / irreversible:** Clear, unambiguous, never softened. "This action cannot be undone."
+
+### Writing Error Messages for Async Operations
+
+Async operations — uploads, exports, background syncs — require a different error model. The user has moved on by the time the error occurs, so the error must re-establish context:
+
+- **Name the operation that failed:** "Your CSV export failed." not "Export failed."
+- **State when it failed:** "Your export failed 2 minutes ago." for non-blocking async errors.
+- **Offer a retry path:** "Try exporting again" should be a button, not just text.
+- **Confirm what was saved vs lost:** "Your changes were saved, but the export did not complete."
+
+Stripe's export errors follow this pattern. GitHub's Actions failure notifications include the step that failed, the exit code reason in plain language, and a direct link to the failing run. Async error messages must be complete enough to stand alone — the user cannot see the original trigger.
+
+### Anti-Patterns
+
+1. **The Cryptic Code.** Exposing error codes, technical exceptions, or stack traces directly to users. "Error 0x80004005: Unspecified error," "NullPointerException at line 247," "ECONNREFUSED." Users cannot act on these. The fix: catch all errors at the UI layer and translate into human language. The technical code can appear in a collapsed "details" section for support teams, but never as the primary message. Showing raw technical output signals that the error path was never designed — it was just left unhandled.
+
+2. **The Blame Game.** Error messages that explicitly or implicitly fault the user. "You entered an invalid value." "You chose a username that is already taken." "Your session expired because you were inactive." Reframe: name the issue without a subject ("That username is taken"), or use the object as subject ("The session timed out after 30 minutes of inactivity"). The user already feels frustrated — do not add guilt. Blaming the user also trains them to distrust the product when errors occur.
+
+3. **The Dead End.** Error messages with no recovery path, no next step, no action. "Something went wrong." "Error occurred." "Unable to process your request." These messages tell the user what happened (minimally) but offer no resolution. Every error must have at minimum one of: a specific action the user can take, a link to support, a status page URL, or a "Retry" button. A dead-end error is the product equivalent of a locked door with no sign explaining how to get in.
+
+4. **The Generic Catch-All.** Using a single vague error for all failure modes — "Something went wrong, please try again" — regardless of whether the issue is a network timeout, validation failure, permission error, or server crash. Each error type warrants a distinct message. A form validation error ("Password is too short") and a connectivity error ("We can't reach our servers") are completely different problems requiring completely different responses. Generic catch-alls hide useful debugging information from users and signal that error states were not designed intentionally.
+
+### Real-World Examples
+
+**Stripe's Payment Error Flow.** Stripe distinguishes between card-specific and account-level errors with different message patterns. Card decline: "Your card was declined. The issuing bank did not approve this charge. Try a different card or contact your bank." Incorrect CVV: "Your card's security code is incorrect. Check the 3-digit number on the back of your card." Each message names the exact problem and provides a specific next step. Stripe never shows raw decline codes to end users — those go only to the merchant dashboard. Stripe's error taxonomy is exhaustive: over 30 distinct decline reasons each with a unique user-facing message.
+
+**GitHub's Form Validation.** GitHub highlights error fields with a red border and places the error message directly below the field. Repository name conflict: "Name has already been taken." Username requirements: "Username may only contain alphanumeric characters or single hyphens, and cannot begin or end with a hyphen." GitHub relies entirely on inline messages, keeping the feedback localized to the problem field. When multiple fields fail, GitHub focuses on the first field — not all at once — to avoid overwhelming the user.
+
+**Notion's Sync Error Handling.** Notion surfaces sync conflicts with a non-blocking notification: "Someone else edited this page while you were working. We've kept both versions — choose which to keep." This three-part message names what happened, explains the consequence (both versions preserved), and provides a clear action (choose). The tone matches Notion's calm, collaborative voice. Notion avoids panic language like "WARNING: conflict detected" — the situation is resolved, so the message is calm.
+
+**Shopify's Checkout Errors.** Shopify uses a page-level error count ("Please fix 2 errors to continue") with anchor links to each field, combined with inline messages below each field. This dual-layer approach is the gold standard for long or multi-section forms. The count gives scope; the anchor links eliminate scrolling; the inline messages provide specific context at the point of correction. Shopify also retains the user's valid data across the error — the fields that were correct remain filled.
+
+## Source
+
+- NNGroup — "Error Message Guidelines" (2001, updated 2020), https://www.nngroup.com/articles/error-message-guidelines/
+- Google Material Design — Text field error states, https://m3.material.io/components/text-fields/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), ch. 7: Error Messages
+- Nielsen, J. — "User Interface Design Heuristics #9: Help users recognize, diagnose, and recover from errors" (1994)
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), error and failure state patterns
+- Wroblewski, L. — _Web Form Design_ (2008), inline validation and error placement research
+
+### Internationalizing Error Messages
+
+Error messages that work in English may fail in other languages. Design error copy for localization:
+
+- **Avoid string concatenation:** "Your " + fieldName + " is invalid" breaks in languages with different word order. Write complete sentences: "That email address is not valid."
+- **Avoid relative time expressions:** "Please try again in a few minutes" is difficult to localize consistently. Use explicit guidance: "Please try again in 5 minutes" or "Please try again later."
+- **Gender-neutral phrasing:** "Your account has been locked" avoids gendered constructions that may not translate directly.
+- **Avoid idioms:** "Something went sideways" does not translate. "Something went wrong" does.
+- **Test with German:** German compound words and longer translations regularly reveal UI overflow issues in error message containers. If the error container holds German error copy, it will hold all major languages.
+
+Error messages that are designed for localization from the start are shorter, more literal, and easier for translators — which is also a benefit for English-language users who benefit from the same clarity.
+
+## Process
+
+1. Identify whether the error is field-level, form-level, or system-level — each requires a different placement and pattern.
+2. Write the three-part message: what failed, why it failed (when known), what to do next.
+3. Remove any technical language, error codes, or jargon — translate to user vocabulary.
+4. Verify the tone matches the product's voice guidelines and does not assign blame to the user.
+5. Confirm the message includes a recovery action or link — no dead ends.
+
+### Error Message Review Checklist
+
+Before shipping any error message, verify each item:
+
+| Check                      | Pass Criteria                                             |
+| -------------------------- | --------------------------------------------------------- |
+| Three-part structure       | What + why (if known) + how to fix                        |
+| No technical language      | No codes, exceptions, or stack traces visible             |
+| Placement correct          | Field-level inline; system-level in appropriate component |
+| No user blame              | No "you entered," "you chose," "your mistake"             |
+| Recovery path present      | Action button, retry link, or status URL                  |
+| Tone matches product voice | Same voice as success states and onboarding               |
+| Constraint specificity     | Names the specific unmet constraint, not "invalid"        |
+| Async context preserved    | Async error re-establishes what was being processed       |
+
+Failing any item in this checklist means the error message needs revision before shipping. Incomplete error messages erode user trust in proportion to their frequency — in a product where errors happen often (form-heavy workflows, developer tools), error message quality directly affects overall product quality perception.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All error messages follow the three-part structure: what, why (when known), how to fix.
+- Field-level errors appear inline next to the field, not only in a top-of-page summary.
+- No error message exposes technical codes, exception names, or stack traces to users.
+- Every error message includes a recovery action, retry option, or status link — no dead ends.
+- Error tone matches the product's voice guidelines and avoids attributing blame to the user.
+- Async operation errors re-establish context and include a specific retry or escalation path.

package/dist/agents/skills/gemini-cli/ux-error-messages/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-error-messages
+version: "1.0.0"
+description: Error messages — what went wrong, why it matters, how to fix it, the three-part error pattern for clear, actionable error communication
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-voice-tone
+  - ux-plain-language
+  - design-empty-error-states
+  - design-feedback-patterns
+stack_signals: []
+keywords:
+  - error-messages
+  - validation
+  - user-feedback
+  - error-recovery
+  - inline-errors
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []