Index of every page on this site: llms.txt
All skills
block avatar

/assistive-ux

@77422a9
by Block Open Sourceblock/berd1.1k stars
137
Run it yourself

Use when adding, reviewing, designing, testing, or managing Assistive UX moments in Berd, including discover, suggest, and autoApply guidance, adaptive settings, behavior signals, retirement rules, or changes under src/shared/assistive-ux.

  • 1 file
  • 2.8 KB
  • Updated 3 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/block/berd/assistive-ux

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈63 tokens for metadata: the name and description. ≈635 when used: this file.

Description uses 3.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈254 characters, or 3.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Assistive UX

Use this skill for Berd product intelligence moments that teach, suggest, or adapt settings based on user behavior.

Before changing code, read docs/assistive-ux.md. Treat that doc as the source of product intent and architecture.

Core Rule

Keep assistive state separate from user settings:

User settings answer: what should the product do?
Assistive UX answers: what has the app shown, observed, accepted, retired, or applied?

Do not store guidance lifecycle state inside a feature setting. Do not use assistive state as the source of truth for product behavior.

Types

  • discover: teaches that a control, setting, or capability exists. It should not change settings.
  • suggest: notices a repeated behavior and asks before changing a setting.
  • autoApply: changes a reversible local setting only after strong evidence, then explains the change and offers undo.

Use autoApply conservatively. Never auto-apply changes involving secrets, credentials, permissions, destructive actions, provider setup, billing-like behavior, or hard-to-reverse choices.

Implementation Workflow

  1. Define or update the rule in src/shared/assistive-ux/registry.ts.
  2. Keep lifecycle reads and writes in src/shared/assistive-ux/runtime.ts and src/shared/assistive-ux/state.ts.
  3. Render the moment from the relevant feature surface.
  4. Retire the moment when the user accepts it, dismisses it, sees it enough times, or manually changes the related setting.
  5. If the moment changes a setting, call the setting's public setter and provide an undo path when the change is automatic.
  6. Keep stored signals coarse. Do not store chat text, file paths, provider secrets, credentials, or message contents.

UX Checklist

Before shipping, confirm:

  • The moment appears close to the behavior it helps with.
  • The copy explains the next action without selling the feature.
  • The primary workflow still has visual priority.
  • The moment has a clear retirement path.
  • Repeated exposure is capped.
  • Manual setting changes stop or reset related guidance.
  • The behavior works in light and dark themes.

Testing

Add focused tests for:

  • fresh eligibility
  • shown-count updates
  • max-show expiration
  • acceptance or dismissal retirement
  • related setting-change retirement
  • invalid localStorage fallback
  • any feature surface that renders or applies the moment

For broad behavior, add Playwright coverage only when the flow benefits from real app navigation or persistence across reloads.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 77422a9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 3 months ago

README badge

README badge for block/berd/assistive-ux