@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/gemini-cli/ux-tooltip-contextual-help/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-tooltip-contextual-help
+version: "1.0.0"
+description: Tooltip and contextual help writing — when to use tooltips, what to put in them, and progressive disclosure patterns that educate without interrupting
+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-plain-language
+  - ux-content-hierarchy
+stack_signals: []
+keywords:
+  - tooltip
+  - contextual-help
+  - progressive-disclosure
+  - help-text
+  - hover
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ux-voice-tone/SKILL.md

@@ -0,0 +1,150 @@
+# Voice and Tone
+
+> Voice and tone in UI writing — defining voice (constant) vs tone (contextual), formality calibration, and emotional register
+
+## When to Use
+
+- Establishing or documenting a product's voice guidelines for the first time
+- Calibrating tone for different UI contexts -- error states, success messages, onboarding, destructive actions
+- Writing for emotionally charged moments -- failed payments, account deletion, data loss warnings
+- Auditing existing UI text for voice consistency across features and teams
+- Onboarding new writers or developers who will contribute UI text
+- Building a voice and tone style guide for a design system
+- Reviewing destructive action dialogs, payment flows, and security alerts for tonal appropriateness
+- Transitioning a product from engineer-written UI text to a consistent voice system
+- Defining upgrade and billing prompt language that respects user autonomy
+- NOT for: marketing brand guidelines or editorial voice for blog content
+- NOT for: visual brand identity (logos, color palette, typography)
+
+## Instructions
+
+1. **Voice is constant, tone varies by context.** Voice is your product's personality -- it stays the same whether the user is celebrating or panicking. Tone is the emotional register you apply to that personality depending on the situation. Slack's voice is always casual and friendly, but its tone shifts from playful ("You're all caught up!") to serious ("This will permanently delete #engineering and all its messages. This cannot be undone.") to supportive ("Having trouble? We can help."). The distinction matters because teams that conflate voice and tone either sound robotic in every context or sound flippant during serious moments.
+
+2. **Define your voice with three to five adjectives and their opposites.** Mailchimp's voice guide is the industry standard: "Funny but not goofy. Confident but not cocky. Smart but not stodgy. Informal but not sloppy. Helpful but not overbearing." The opposites prevent misinterpretation. Without them, "funny" can drift into slapstick, "confident" into arrogance, "informal" into unprofessional. Stripe defines its voice as "clear, not clever" -- prioritizing comprehension over personality. Notion's voice is "simple, not simplistic" -- accessible without being patronizing. Write these down. Put them in a shared document. Reference them in code reviews.
+
+3. **Calibrate formality to consequences.** The higher the stakes, the more formal the tone. A dashboard greeting can be casual: "Welcome back, Jordan." A payment failure must be direct and clear: "Your payment of $49.99 failed. Update your payment method to avoid service interruption." Stripe follows this gradient precisely: dashboard navigation is conversational, API documentation is technical but accessible, payment error messages are formal and specific, and fraud warnings are urgent and imperative. Map each UI context to a point on the formality spectrum before writing.
+
+4. **Match the user's emotional state before redirecting it.** When a user encounters an error, they are frustrated. Starting with cheerfulness ("Oops! Something went wrong!") invalidates their frustration and erodes trust. Start by acknowledging reality: "We couldn't process your payment." Then provide the path forward: "Try a different card or contact your bank." Apple's error messages follow this pattern: state the problem factually, then offer one or two concrete actions. Never lead with false positivity when the user is experiencing a negative outcome.
+
+5. **Use the tone spectrum: playful, neutral, serious, urgent.** Map every UI context to a point on this four-level spectrum. Success confirmations: playful to neutral ("Your project is live!"). Informational messages: neutral ("Your trial ends in 14 days."). Error recovery: serious ("We couldn't save your changes. Your draft is preserved locally."). Security warnings: urgent ("Unusual sign-in detected. Was this you?"). The spectrum prevents two common failures: treating everything as neutral (robotic), or treating everything as playful (tone-deaf). Linear maps its spectrum clearly: issue creation is neutral, critical bug labels are serious, and subscription changes are formal.
+
+6. **Avoid false cheerfulness in negative moments.** "Oops!" before a payment failure. A winking emoji after a deletion warning. "Uh oh!" when the server is down. False cheerfulness signals that the product does not take the user's problem seriously. The rule: if the user cannot undo the situation immediately, do not use playful language. GitHub's repository deletion dialog is a model of appropriate gravity: no humor, no softening, just the facts and a confirmation that requires typing the repository name. Compare this with products that say "Whoopsie! Your account has been deactivated!" -- the mismatch between the severity and the tone destroys credibility.
+
+7. **Test tone with the "read it out loud to a stranger" method.** Read the UI text aloud to someone unfamiliar with the product, in the voice you intend. If the text sounds condescending, robotic, or inappropriately casual, it will read that way too. This test catches tone mismatches that are invisible when reading silently. Particularly effective for error messages: read "We're sorry, but the thing you were trying to do didn't work out. Please try again later or contact our friendly support team!" aloud and hear how patronizing it sounds. Then read "Upload failed. File exceeds the 10 MB limit." and hear how much more respectful it is.
+
+## Details
+
+### Voice Documentation Template
+
+A voice document should contain four sections that any team member can reference when writing UI text:
+
+**Voice principles.** Three to five adjective pairs with examples. Each pair gets a "this, not that" column:
+
+| Principle                | This (do)                                       | Not that (don't)                                    |
+| ------------------------ | ----------------------------------------------- | --------------------------------------------------- |
+| Friendly, not familiar   | "Welcome back, Jordan"                          | "Hey hey, look who's back!"                         |
+| Confident, not arrogant  | "Your data is encrypted at rest and in transit" | "We have the most secure platform on the market"    |
+| Direct, not blunt        | "Your card was declined"                        | "Payment failure: card_declined"                    |
+| Helpful, not overbearing | "Need help? Visit our docs"                     | "Did you know you can also try these 5 features..." |
+| Concise, not curt        | "Saved"                                         | "S."                                                |
+
+**Tone mapping.** A matrix that maps UI contexts to tone levels:
+
+| Context              | Tone Level     | Example                                                |
+| -------------------- | -------------- | ------------------------------------------------------ |
+| Onboarding           | Warm           | "Let's set up your workspace. It takes about 2 min"    |
+| Success confirmation | Positive       | "Your project is live!"                                |
+| Neutral information  | Matter-of-fact | "Your plan includes 5 team members"                    |
+| Warning              | Serious        | "You've used 90% of your storage"                      |
+| Error recovery       | Empathetic     | "We couldn't connect. Your work is saved locally"      |
+| Destructive action   | Grave          | "This will permanently delete all project data"        |
+| Security alert       | Urgent         | "New sign-in from unknown device. Secure your account" |
+
+**Vocabulary list.** Preferred terms and banned terms. Stripe's vocabulary: "customer" not "user," "decline" not "reject," "update" not "change." This list prevents drift across teams and ensures consistency even when multiple writers contribute.
+
+**Exception list.** Specific contexts where the standard voice shifts. Legal text, compliance warnings, and accessibility descriptions may require more formal language than the standard voice. Document these exceptions explicitly so writers do not force casual voice into contexts that require formality.
+
+**Voice audit process.** Review all UI text quarterly by pulling a random sample of 50 strings from across the product. Score each string on voice consistency (1-5) and tonal appropriateness (1-5). Strings scoring below 3 on either dimension should be rewritten. Track the average score over time to measure voice maturation. Atlassian runs this process and publishes the results internally to maintain accountability across teams.
+
+### Tone Calibration for Common UI Moments
+
+Specific guidance for the most frequently encountered UI contexts where tone decisions have the highest impact:
+
+**Onboarding and first-run.** The user is forming their first impression. Tone should be warm and encouraging without being presumptuous. Assume nothing about the user's expertise. Notion's onboarding says "Welcome to Notion. Let's set up your workspace" -- warm, simple, no jargon. Avoid over-excitement ("OMG you're going to LOVE this!") and avoid cold efficiency ("Step 1 of 5: Configure workspace settings").
+
+**Empty states.** The user sees nothing and may feel lost. Tone should be reassuring and action-oriented. "No projects yet" is neutral and clear. "Create your first project to start collaborating" adds a gentle nudge without pressure. GitHub's empty repository state achieves this by providing copy-paste commands -- the tone says "we've made this easy for you" without stating it.
+
+**Loading and waiting.** The user is idle and potentially anxious. Tone should be calm and informative. "Loading your dashboard..." is standard. Slack adds personality with loading messages like "Herding cats..." but keeps them short and rotates them to avoid repetition fatigue. If loading takes more than a few seconds, shift to informational: "Loading 2,847 messages..."
+
+**Upgrade and billing prompts.** The user is being asked to spend money. Tone must be respectful and transparent, never pushy or manipulative. "Your team has grown past the free plan limit of 5 members. See plans." is factual. "Unlock UNLIMITED features NOW!" is aggressive and damages trust. Stripe's billing UI uses professional tone exclusively: clear pricing, no urgency tricks, no countdown timers.
+
+**Account closure.** The user is leaving. Tone should be respectful and friction-free. Acknowledge the decision without guilt-tripping. "We're sorry to see you go" is acceptable. "Are you SURE? You'll lose EVERYTHING!" is manipulative. Provide a clear summary of what will happen and when, with a simple confirmation step.
+
+### The Formality Ladder
+
+Formality is not binary (casual vs. formal). It is a five-rung ladder:
+
+1. **Playful.** Emojis, contractions, humor, first-name address. Appropriate for: welcome messages, achievement celebrations, empty states. Example: Slack's "You're all caught up" with a plant illustration.
+2. **Conversational.** Contractions, second person, friendly but no humor. Appropriate for: dashboard text, navigation labels, feature descriptions. Example: Notion's "Share this page with your team."
+3. **Professional.** Full sentences, no contractions in critical text, second person. Appropriate for: billing information, plan changes, data handling notices. Example: Stripe's "Your subscription will renew on April 15."
+4. **Formal.** Complete sentences, no contractions, specific and unambiguous. Appropriate for: error messages, security alerts, compliance text. Example: GitHub's "Deleting a repository is permanent and cannot be undone."
+5. **Urgent.** Short sentences, imperative mood, action-first. Appropriate for: security breaches, data loss warnings, system outages. Example: "Your account may be compromised. Change your password now."
+
+Most products live primarily at levels 2-3 (conversational to professional). The extremes -- playful and urgent -- should account for less than 10% of total UI text. If more than half of your UI strings are at the playful level, your product will feel unserious. If more than half are at the formal level, it will feel bureaucratic. Audit the distribution periodically and rebalance toward the center.
+
+### Anti-Patterns
+
+1. **The Tone-Deaf Celebration.** Using playful or celebratory language during a negative user experience. "Whoops! Your payment didn't go through!" with a confetti animation. "Yikes, your account has been suspended!" The mismatch between the severity of the situation and the lighthearted tone makes the product seem unaware or uncaring. The fix: error states, failed actions, and account problems always use serious or empathetic tone. Save playful tone for genuinely positive moments.
+
+2. **The Corporate Robot.** Every piece of UI text reads like a legal document or a press release. "The system has successfully processed your request and the resulting modifications have been applied to your account." This happens when legal or compliance teams review UI text without content design input, or when engineers write microcopy by describing what the code does. The fix: rewrite in second person, use contractions, and cut the word count by half. "Your changes are saved."
+
+3. **The Inconsistent Personality.** The product sounds like a different person on every screen. Onboarding is bubbly and emoji-laden. Settings are clinical and passive. Error messages are curt and technical. This happens when multiple writers contribute without a shared voice document. The user experience feels fragmented, as if different departments built different parts of the product -- because they did. The fix: create a voice document (see template above) and require voice review in the same way you require code review.
+
+4. **The Forced Humor.** Injecting jokes, puns, or pop culture references into UI text where they do not serve the user. A 404 page that says "These aren't the droids you're looking for" is memorable the first time and annoying every subsequent visit. Humor in UI text has a shelf life: it delights once and then becomes noise. The fix: humor is acceptable in low-frequency, low-stakes contexts (first-time empty states, 404 pages) but should never appear in high-frequency or high-stakes contexts (dashboards, payment flows, error messages).
+
+5. **The Guilt Trip.** Using emotionally manipulative language when users decline upsells, unsubscribe, or close accounts. "No thanks, I don't want to grow my business" as an opt-out link. "Are you sure? You'll lose access to everything you've built." This pattern, called "confirmshaming," damages trust and brands the product as manipulative. The fix: present choices neutrally. "Keep current plan" and "Upgrade" are both respectful. "No thanks" is a complete, dignified opt-out. The user's decision to leave or decline deserves the same respect as their decision to join.
+
+### Real-World Examples
+
+**Mailchimp's Voice and Tone Guide.** Mailchimp published one of the first and most influential voice and tone guides in tech. Their key insight: voice is who you are, tone is how you adapt. The guide provides specific examples for every content type -- success messages, error messages, marketing emails, legal text -- showing how the same Mailchimp voice (informal, funny, empowering) adjusts tone for each context. A success message: "High fives! Your campaign is on its way." A failed send: "Your campaign wasn't sent. Here's what happened." The guide explicitly addresses the emotional state of the user in each context and prescribes the appropriate tone response. This document became the template for voice guides at Shopify, Atlassian, and dozens of other companies.
+
+**Slack's Personality in Microcopy.** Slack maintains a consistent casual voice across thousands of UI strings while precisely modulating tone. Channel creation: "Give your channel a name" (conversational). File upload: "Drag files here" (minimal). Thread summary: "3 replies" (utilitarian). Account deletion: "This is permanent. Your messages, files, and integrations will be removed." (grave). The consistency of voice across these wildly different tonal requirements is what makes Slack feel like a coherent product rather than a collection of features. Slack achieves this by maintaining an internal content design team that reviews every UI string before release, using a shared voice checklist that maps each string to the tone spectrum.
+
+**Stripe's Formality Gradient.** Stripe demonstrates how a single product can use the entire formality ladder appropriately. Dashboard welcome: "Welcome back" (conversational). API documentation: "Create a PaymentIntent with the amount and currency" (professional). Payment error: "Your card was declined. Try a different payment method or contact your bank." (formal, specific). Fraud alert: "Suspicious activity detected on your account. Review recent transactions immediately." (urgent). Each level of formality matches the consequence level of the interaction, and the transition between levels feels natural because the underlying voice -- clear, direct, respectful -- remains constant.
+
+**GitHub's Gravity Spectrum.** GitHub provides an instructive case study in how tone scales with consequence. Creating a new file: "Create new file" (neutral, imperative). Branch protection rules: "Require pull request reviews before merging" (professional, descriptive). Repository visibility change: "Change repository visibility. You are about to make this repository public. This action is visible to the entire internet." (formal, explicit consequence). Repository deletion: "This action cannot be undone. This will permanently delete the repository, wiki, issues, comments, packages, secrets, workflow runs, and remove all collaborator associations." (grave, exhaustive enumeration of consequences). The escalation is seamless because GitHub's underlying voice -- precise, technically literate, respectful of the developer audience -- anchors every tonal shift.
+
+**Linear's Professional Calm.** Linear maintains what might be described as "professional calm" -- a voice that is efficient without being cold, and friendly without being chatty. Issue creation: "Create issue" (minimal). Status updates: "Issue moved to In Progress" (factual). Sprint completion: "Sprint 23 completed. 12 of 15 issues done." (data-driven, no celebration or judgment). This voice works because Linear's audience (engineering teams) values signal-to-noise ratio. Every word in Linear's UI carries information; there is no filler, no personality for personality's sake. The lesson: voice does not require personality -- it requires consistency.
+
+## Source
+
+- Mailchimp Content Style Guide -- Voice and Tone, https://styleguide.mailchimp.com/voice-and-tone/
+- NNGroup -- "Tone of Voice in UX" series (2016-2020), research on how tone affects perceived credibility and trustworthiness
+- Kiefer Lee, K. and Yifrah, K. -- _Nicely Said: Writing for the Web with Style and Purpose_ (2014), the definitive guide to writing voice documentation
+- Apple Human Interface Guidelines -- Writing section, emotional register guidance for system-level messages
+- Google Material Design -- Writing guidelines, tone calibration per component type, https://m3.material.io/foundations/content/overview
+- Podmajersky, T. -- _Strategic Writing for UX_ (2019), voice-first content strategy for product teams
+- Shopify Polaris -- Voice and Tone guidelines, https://polaris.shopify.com/content/voice-and-tone
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Create or reference your product's voice document with adjective pairs and tone mapping.
+3. Apply the tone spectrum to each UI context, matching formality to consequence level.
+4. Run the read-aloud test on all high-stakes UI text (errors, destructive actions, security).
+5. Verify your implementation against the details and anti-patterns listed above.
+
+## 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
+
+- A voice document exists with three to five adjective pairs and their "this, not that" examples.
+- Every UI context is mapped to a point on the tone spectrum (playful, neutral, serious, urgent).
+- Error messages, destructive actions, and security alerts use serious or urgent tone -- never playful.
+- The product reads as one consistent personality across all screens and features.
+- No false cheerfulness appears in negative-outcome contexts.
+- Upgrade prompts and account closure flows use respectful, non-manipulative language.
+- The read-aloud test passes for all high-stakes UI text -- error messages, destructive actions, and security alerts sound appropriate when spoken to a stranger.

package/dist/agents/skills/gemini-cli/ux-voice-tone/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-voice-tone
+version: "1.0.0"
+description: Voice and tone in UI writing — defining voice (constant) vs tone (contextual), formality calibration, and emotional register
+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-plain-language
+  - ux-inclusive-language
+stack_signals: []
+keywords:
+  - voice
+  - tone
+  - formality
+  - brand-voice
+  - emotional-register
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ux-writing-for-scanning/SKILL.md

@@ -0,0 +1,150 @@
+# Writing for Scanning
+
+> Writing for scanning — F-pattern, front-loading keywords, chunking, bullet vs prose decisions for UI text
+
+## When to Use
+
+- Writing any UI text longer than one sentence -- descriptions, help text, feature explanations
+- Designing help pages, knowledge base articles, and in-app documentation
+- Creating feature descriptions for settings pages, marketing pages within the app, and changelogs
+- Writing changelog entries, release notes, and update summaries
+- Composing email notifications, digest emails, and alert messages that users process in seconds
+- Organizing lists of features, permissions, or options in preference panels
+- Reviewing existing UI text that users report as "too long" or "hard to find things"
+- Structuring API documentation, developer guides, and technical reference material for quick lookup
+- Designing pricing pages and feature comparison tables for rapid evaluation
+- NOT for: legal text where completeness and precision override scannability
+- NOT for: creative writing, brand storytelling, or marketing copy where engagement requires linear reading
+
+## Instructions
+
+1. **Front-load the keyword in every line.** Users scan the first two words of any text element -- eye-tracking research from NNGroup confirms this consistently. The distinguishing word must come first. "Export data" is scannable because "Export" is the keyword. "Click here to export your data" buries the keyword at word four. In a list of actions, front-loaded keywords let the user find the right option by scanning only the left edge:
+
+   | Front-loaded (scannable) | Back-loaded (not scannable)       |
+   | ------------------------ | --------------------------------- |
+   | Export data              | Click here to export your data    |
+   | Delete project           | Would you like to delete this?    |
+   | Notification settings    | Settings for your notifications   |
+   | Billing history          | View your past billing statements |
+   | Team members             | Manage people in your team        |
+
+2. **Use the F-pattern.** Eye-tracking studies show that users read web content in an F-shaped pattern: they read the first line fully, then scan the left edges of subsequent lines. This means the first line of any text block gets the most attention, and subsequent lines are only scanned at their left margins. Design for this: put the most important information in the first line, and ensure that each subsequent line starts with a meaningful keyword. GitHub's repository file listing exploits the F-pattern: file names (the keywords) are on the left edge, and metadata (size, last modified) is on the right where scanning eyes may not reach.
+
+3. **Bullets over prose when listing three or more items.** A five-item paragraph is unreadable. A five-item bulleted list is instantly scannable. The threshold is three: if you are listing three or more items, use bullets. Below three, inline text is acceptable. This is not about aesthetics -- it is about cognitive processing. Bullets create visual separation between items, allowing the user to process each item independently. Stripe's pricing page uses bullets for feature lists: "Unlimited API calls," "Real-time webhooks," "3D Secure authentication." Each feature is instantly identifiable.
+
+4. **Chunk text into groups of three to five related items.** George Miller's research on working memory suggests that humans process information most effectively in chunks of three to seven items. For UI text, the practical limit is three to five. A settings page with 20 ungrouped options overwhelms. The same 20 options in four groups of five are manageable. Each group should have a label that names the category. Slack's notification preferences chunk options into groups: "Activity in channels," "Direct messages," "Mentions," "Threads" -- each group contains three to five specific settings.
+
+5. **Use bold for scannable anchors.** One bolded term per paragraph gives the scanning eye a landing point. The bolded word should be the keyword that tells the user what the paragraph is about. If a user scans a page and reads only the bolded words, they should get a summary of the page's content. This document uses this technique: each instruction starts with a bolded principle that can be read independently of the explanation that follows. Apple's support articles use bold for key terms within paragraphs, creating a scannable path through dense content.
+
+6. **Keep paragraphs to three sentences maximum in UI context.** A paragraph in a novel can be a page long. A paragraph in UI text should be three sentences at most. If the paragraph is longer, it should be split into smaller paragraphs, converted to a bulleted list, or moved behind a progressive disclosure control. Mobile screens make this constraint even tighter: on a phone, a three-sentence paragraph can fill the viewport. Notion's feature descriptions follow this rule: each explanation is two to three sentences, with whitespace between paragraphs that communicates "new thought."
+
+7. **Use parallel structure in lists.** Every bullet in a list should start with the same part of speech. If the first bullet starts with a verb, every bullet starts with a verb. If the first starts with a noun, every bullet starts with a noun. Parallel structure allows the scanning eye to skip the repeated pattern and focus on the unique content. The three most common parallel patterns in UI text are: verb-first for action lists ("Create projects," "Assign members"), noun-first for feature lists ("Unlimited storage," "Priority support"), and adjective-first for attribute lists ("Fast deployment," "Secure hosting").
+
+   | Parallel (scannable)  | Non-parallel (jarring)             |
+   | --------------------- | ---------------------------------- |
+   | - Create projects     | - Create projects                  |
+   | - Assign team members | - Team members can be assigned     |
+   | - Track progress      | - For tracking progress            |
+   | - Export reports      | - Reports are available for export |
+
+8. **Whitespace is content.** A blank line between groups communicates "new topic" faster than any heading. Whitespace is not wasted space -- it is a scanning aid that allows the eye to distinguish between groups, sections, and individual items. Remove whitespace and the page becomes a wall of text regardless of how well the individual sentences are written. GitHub's issue list uses whitespace between issues to make each item individually identifiable. Stripe's transaction list uses alternating backgrounds and consistent spacing to achieve the same effect.
+
+## Details
+
+### The F-Pattern in Practice
+
+The F-pattern has three components, each of which has implications for UI writing:
+
+**Horizontal bar 1 (top).** Users read the first line or heading of a text block almost completely. Implication: the first line must contain the most important information. If a settings description starts with "This feature allows you to..." the user has already read eight words before encountering the actual feature name.
+
+**Horizontal bar 2 (middle).** Users read a second horizontal line partway through the content, typically shorter than the first. Implication: if you have two key points, put the second one at the visual midpoint of the text block, not at the end.
+
+**Vertical bar (left edge).** Users scan the left edge of subsequent lines. Implication: every line must start with a meaningful keyword. Indent and whitespace on the left edge break the scanning pattern.
+
+The F-pattern degrades when content is well-formatted with clear headings, bolded anchors, and bulleted lists -- users switch to a more thorough scanning pattern because the formatting signals that the content is worth reading. This is the goal: writing for scanning does not mean writing less, it means formatting so that scanning is productive.
+
+### Bullet vs Prose Decision Matrix
+
+| Condition                                  | Use bullets    | Use prose |
+| ------------------------------------------ | -------------- | --------- |
+| Listing 3+ discrete items                  | Yes            | No        |
+| Comparing features or options              | Yes            | No        |
+| Steps in a process (ordered)               | Yes (numbered) | No        |
+| Explaining a concept that requires context | No             | Yes       |
+| Providing a narrative explanation          | No             | Yes       |
+| Listing 1-2 items inline                   | No             | Yes       |
+| Describing cause and effect                | No             | Yes       |
+| Listing prerequisites or requirements      | Yes            | No        |
+
+The most common mistake is using prose for lists. The second most common mistake is using bullets for explanations that require connective tissue between ideas. Bullets remove the relationship between items -- each bullet is processed independently. When the relationship matters (cause and effect, sequence, contrast), prose preserves it.
+
+### Character-Count Guidelines by Component
+
+Scanning speed is directly related to text length. These guidelines ensure that each component type is sized for scanning:
+
+| Component          | Characters | Words | Scanning time |
+| ------------------ | ---------- | ----- | ------------- |
+| Sidebar label      | 15-25      | 1-3   | < 1 second    |
+| Button             | 10-25      | 1-4   | < 1 second    |
+| Tab label          | 10-20      | 1-2   | < 1 second    |
+| Tooltip            | 40-80      | 5-12  | 2-3 seconds   |
+| Toast notification | 40-120     | 5-15  | 3-5 seconds   |
+| Card description   | 80-150     | 10-20 | 5-8 seconds   |
+| Help text block    | 150-300    | 20-40 | 8-15 seconds  |
+| Changelog entry    | 200-400    | 25-50 | 10-20 seconds |
+
+### Anti-Patterns
+
+1. **The Prose Block.** A feature description, help article, or settings explanation written as a single dense paragraph with no headings, no bullets, no bold text, and no whitespace breaks. The user sees a wall of text and skips it entirely. This is the most common scanning anti-pattern and the most damaging: users who need the information will not read it, and users who do not need it are annoyed by the visual weight. The fix: break every paragraph longer than three sentences into smaller chunks. Convert lists embedded in prose into actual bullet points. Add one bolded anchor per paragraph.
+
+2. **The Endless List.** A bulleted list with 15 or more items and no subcategories. The list was created to aid scanning, but at this length, it defeats the purpose -- the user cannot hold 15 items in working memory and must scroll repeatedly to find the one they need. The fix: group the items into subcategories of three to five items each. Add a subheading for each group. If the items cannot be grouped, consider whether a different presentation (table, grid, search) would serve better.
+
+3. **The Buried Keyword.** Text where the distinguishing word is in the middle or end of the line instead of at the beginning. "Click on the settings icon to configure your notification preferences" buries "notification preferences" at the end. "Notification preferences" should be the first two words. The fix: restructure every line so the keyword comes first. "Notification preferences -- click the settings icon to configure." Or better: remove the instruction entirely and just label the link "Notification preferences."
+
+4. **The False Parallel.** A list that appears to use parallel structure but breaks it partway through. The first three bullets start with verbs: "Create projects," "Assign members," "Track progress." Then the fourth bullet says "Reports can be exported." The break in parallel structure is jarring and slows scanning because the user's pattern-matching fails. The fix: commit to one grammatical structure for the entire list and do not deviate.
+
+### Real-World Examples
+
+**GitHub's Changelog Format.** GitHub's changelog entries demonstrate structured scanning at scale. Each entry has a date heading, a category label (Features, Bug fixes, Changes), and bullet points that front-load the affected feature: "Pull requests -- added ability to convert to draft." The category label allows users to skip entire sections (a user looking for bug fixes can skip the Features section). The front-loaded feature name allows scanning within a category. The result: a user can scan a month of changes in under 30 seconds and find the one entry relevant to them.
+
+**Notion's Slash-Command Menu.** Notion's "/" command menu is a masterclass in scannable labeling. Each command is a front-loaded keyword: "To-do list," "Heading 1," "Toggle list," "Quote," "Divider," "Code." No command starts with a verb phrase or explanation. The commands are grouped into categories: "Basic blocks," "Media," "Database," "Embeds." The grouping plus front-loaded labels means a user can find any command with one visual scan of the category labels and one scan of the items within the correct category.
+
+**Stripe's API Documentation.** Stripe's API documentation applies scanning principles to technical content. Each endpoint starts with a one-sentence description that front-loads the action: "Create a customer," "Retrieve a payment intent," "List all charges." Code examples are chunked into labeled blocks (curl, Ruby, Python, Node). Parameters are listed in a table with the parameter name (keyword) on the left edge. Required parameters are visually distinguished from optional ones. The result: a developer can find the right endpoint, understand its purpose, and locate the specific parameter they need in under 60 seconds.
+
+**Linear's Issue List Scanning.** Linear's issue list is designed for rapid scanning by engineering teams who process dozens of issues daily. Each issue row front-loads the issue identifier (LIN-1234) followed by the title. Status, priority, and assignee are encoded as compact icons on the left edge -- the scanning eye can process them without reading text. Labels appear as colored chips after the title. The list groups issues by status (Backlog, Todo, In Progress, Done) with clear section dividers. A user can scan 50 issues and find the ones relevant to them in under 10 seconds because every scanning aid is present: front-loaded identifiers, visual status encoding, chunked grouping, and parallel structure across rows.
+
+## Source
+
+- NNGroup -- "F-Shaped Pattern for Reading Web Content" (2006), the foundational eye-tracking study
+- NNGroup -- "How Users Read on the Web" (1997, updated 2020), evidence that users scan rather than read
+- Miller, G.A. -- "The Magical Number Seven, Plus or Minus Two" (1956), working memory capacity research
+- Krug, S. -- _Don't Make Me Think_ (2014), practical scanning optimization for web content
+- Google Material Design -- Writing guidelines, content structure for scanning
+- Redish, J. -- _Letting Go of the Words_ (2012), writing for the web with scanning-first principles
+- NNGroup -- "How People Read Online: New and Old Findings" (2020), updated scanning behavior research
+- Apple Human Interface Guidelines -- Writing section, text brevity and structure guidelines
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Audit existing text for front-loaded keywords, parallel structure, and appropriate chunking.
+3. Convert prose blocks to bulleted lists where listing three or more items.
+4. Apply the F-pattern: most important information first, keywords on left edges.
+5. Verify your implementation against the anti-patterns listed above.
+
+## 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 text element front-loads its keyword in the first two words.
+- Lists of three or more items use bullets, not embedded prose.
+- All bulleted lists use parallel grammatical structure.
+- No paragraph in UI context exceeds three sentences.
+- Text blocks are chunked into groups of three to five related items with category labels.
+- Bold anchors appear in every paragraph longer than one sentence.
+- Changelog and release note entries use category labels and front-loaded feature names.
+- Tables are used for structured comparisons; bulleted lists for unordered items; numbered lists for sequential steps.
+- Whitespace separates groups visually -- no section runs into the next without a clear break.

package/dist/agents/skills/gemini-cli/ux-writing-for-scanning/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-writing-for-scanning
+version: "1.0.0"
+description: Writing for scanning — F-pattern, front-loading keywords, chunking, bullet vs prose decisions for UI text
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-content-hierarchy
+  - ux-plain-language
+  - ux-active-voice
+  - ux-microcopy-principles
+  - design-readability
+stack_signals: []
+keywords:
+  - scanning
+  - f-pattern
+  - front-loading
+  - chunking
+  - scanability
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/validate-context-engineering/skill.yaml

@@ -1,6 +1,7 @@
 name: validate-context-engineering
 version: "1.0.0"
 description: Validate repository context engineering practices (AGENTS.md, doc coverage, knowledge map)
+stability: static
 cognitive_mode: meticulous-verifier
 triggers:
   - manual

package/dist/agents/skills/gemini-cli/vue-async-components/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-async-components
 version: '1.0.0'
 description: Load Vue components lazily to reduce initial bundle size using defineAsyncComponent
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-component-events/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-component-events
 version: '1.0.0'
 description: Communicate from child to parent components using emits and defineEmits
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-composables-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-composables-pattern
 version: '1.0.0'
 description: Extract and reuse stateful logic across components using Vue composables
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-directive-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-directive-pattern
 version: '1.0.0'
 description: Create custom Vue directives for low-level DOM manipulation and reusable DOM behavior
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-pinia-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-pinia-pattern
 version: '1.0.0'
 description: Manage shared application state with Pinia stores in the Options or Setup style
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-provide-inject/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-provide-inject
 version: '1.0.0'
 description: Share data across a component tree without prop-drilling using provide/inject
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-reactive-refs/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-reactive-refs
 version: '1.0.0'
 description: Create and manage reactive primitive values and objects using ref and reactive
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-renderless-components/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-renderless-components
 version: '1.0.0'
 description: Extract behavior into components that render nothing, delegating all rendering to the consumer via slots
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-slots-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-slots-pattern
 version: '1.0.0'
 description: Use named, scoped, and dynamic slots to build flexible, composable component APIs
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-teleport-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-teleport-pattern
 version: '1.0.0'
 description: Render a component's HTML at a different location in the DOM using Vue's Teleport
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/vue-watchers-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: vue-watchers-pattern
 version: '1.0.0'
 description: React to data changes with watch and watchEffect for side effects and async operations
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-actor-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-actor-pattern
 version: '1.0.0'
 description: Spawn and manage child actors for independent concurrent state machines
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-guards-actions/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-guards-actions
 version: '1.0.0'
 description: Control transitions with guards and execute side effects with actions
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-history-states/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-history-states
 version: '1.0.0'
 description: Remember and restore previous state configurations with history states
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-invoke-pattern/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-invoke-pattern
 version: '1.0.0'
 description: Invoke promises, callbacks, and child machines as services in state nodes
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-machine-definition/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-machine-definition
 version: '1.0.0'
 description: Define statecharts with createMachine for explicit state transitions and context
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-parallel-states/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-parallel-states
 version: '1.0.0'
 description: Model concurrent state regions with parallel state nodes
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-react-integration/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-react-integration
 version: '1.0.0'
 description: Connect XState machines to React components with useMachine and useActor hooks
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-testing-patterns/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-testing-patterns
 version: '1.0.0'
 description: Test XState machines with model-based testing and direct state assertions
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-typegen/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-typegen
 version: '1.0.0'
 description: Generate full type safety for XState machines with typegen and setup patterns
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3

package/dist/agents/skills/gemini-cli/xstate-visualization/skill.yaml

@@ -1,6 +1,7 @@
 name: xstate-visualization
 version: '1.0.0'
 description: Visualize and inspect XState machines with Stately Inspector and VS Code extension
+stability: static
 cognitive_mode: advisory-guide
 type: knowledge
 tier: 3