agentleFS
baijunjiebaijunjie/octoboard/.claude/skills/agent-gallery/SKILL.md

agent-gallery

Skill5 starsChanged 2 days agoMITView on GitHub

Entry point for the UI state gallery — keep the gallery in step after a change to UI states, mocks or the interface contract mocks depend on, handle a failed quick check, start a preview from this task's branch for the user to confirm at delivery, and clean it up after confirmation. Bring it to mind when a UI state is added or changed, or a UI change is to be handed to the user for confirmation. Use when the user says "add a gallery scenario", "show this state in the gallery", "the gallery is out of date", "clean up the gallery", "start a preview for me".

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 10 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When unsure, report back: stop, spell out what needs deciding (with the options) or what information is missing, together with what you …

    line 9
  2. Distinctive:

    Every failure gets fixed, by cause: where the app code is wrong, change the app code.

    line 117
  3. Distinctive:

    When this change touches the UI, give the user a preview: where whether it is right takes a human eye, wait for confirmation before …

    line 125
  4. Distinctive:

    Start the gallery from this task's branch or working copy, with the app preview where needed, avoiding other working copies as the …

    line 128
  5. Distinctive:

    If no usable preview can be given, say plainly where it is stuck, and do not hand the UI change over as ready to confirm.

    line 133
  6. Distinctive:

    Keep the preview running while waiting for confirmation.

    line 135
  7. Distinctive:

    Never overwrite, stop or uninstall a service or build not started or installed by this working copy.

    line 143
  8. Distinctive:

    Stop the services and uninstall the builds the "Preview scratch location" records, and delete the temporary scenarios, mocks and records …

    line 151
  9. Distinctive:

    Leave alone what you cannot verify (such as a device that cannot be reached), reporting where it is and how to recognise it.

    line 153
  10. Distinctive:

    If the preview is not yet cleaned up at delivery, list in the final reply the services still running and the builds left, how to recognise …

    line 155

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

UI state gallery

What follows sets only principles and the boundaries not to be crossed; judge the remaining details yourself. When unsure, report back: stop, spell out what needs deciding (with the options) or what information is missing, together with what you have already found out, and let the recipient of the report (the user, or the dispatcher passing it on to the user) decide before going on; do not decide for yourself.

The gallery is the dev-only collection of scenarios: each shows one UI state over mock data, needing no real backend, for people to confirm and for the quick check to walk one by one.

Project conventions

"Project conventions" is filled in only by the installer and is not changed at run time. If an item you need is still <…>, a command or path filled in has itself gone stale (unrelated to this change; missing environment such as a database or network is reported as usual and does not count), or an item has to follow the project, stop and ask the user to rerun the installer that installed this skill, saying which item must change and why.

A change that leaves them unable to run is treated as a failed quick check. With several UI packages the table has a row each, and the items below the table say so where packages differ.

ScopeGallery approachWhere scenarios liveOpening the galleryScenario direct entryQuick check (full)Quick check (selected scenarios)
packages/uiSelf-built: gallery.html / gallery-frame.html over packages/ui/src/gallery/ (the real App over the fixture daemon)packages/ui/src/gallery/fixtures/ — the area's file, or a new file listed in its index.ts; how a scenario is built and the conventions for writing one are in packages/ui/README.md, section "The UI state gallery". All of them are gallery-writer's, and so is packages/ui/src/fixtures/, the shared fixtures runtime (fixture daemon, builders, sample data) that both the gallery and the website preview use. The fixture-backed website preview itself (packages/ui/src/website-preview/) is not part of the gallerypnpm gallery --port <free port> in packages/ui (the script's port 5175 is strict, so another checkout serving it fails the start; pick a free one; BROWSER=none in front keeps it from opening a browser tab); the address is the Local: line Vite printshttp://localhost:<port>/gallery.html?scenario=<id>&theme=<light|dark>&lang=<en|zh-Hans|…>, plus width=<px>, height=<px>, held=1 (shortcut modifier held), markdown=<tailwind|github|newsprint|latex> (Markdown style, viewer scenarios) as needed; the frame alone, sized by the browser window, is gallery-frame.html?scenario=<id>&theme=…&lang=…, with held=1, markdown=… and chrome=1 (the desktop window chrome) as neededpnpm gallery:sweep in packages/ui (starts its own dev server on a free port)pnpm gallery:sweep <id or pattern …>, or --group <title>; --list lists the ids
  • UI check items: render smoke (each scenario reaches data-gallery-ready, no [data-gallery-failure] overlay, no uncaught error): self-built packages/ui/scripts/gallery-sweep.mjs on Playwright; light; en only, --lang <list> or --lang all (every language with a catalog) when the user asks for other languages. It loads exactly the scenarios it is given, never skipping one; its page loads wait for a heavy-step slot (the lock pnpm verify also takes). The flags are in packages/ui/README.md, section "Sweeping the gallery". Kept out of the quick check and run only when the user asks: the dark theme, pnpm gallery:sweep --theme dark; narrow widths, pnpm gallery:sweep --width 420,800 (as the page's width control would load the scenarios, since steps must run at any width the control picks); chip geometry, self-built on Playwright, node scripts/gallery-chip-geometry.mjs http://localhost:<port> in packages/ui against a gallery served from this checkout (unlike the sweep it falls back to no other browser: without Playwright's own Chromium, set OCTOBOARD_CHROMIUM to one).
  • What many scenarios share: packages/ui/src/gallery/fixtures/ helpers, the shared fixtures runtime in packages/ui/src/fixtures/ (its fixtureDaemon.ts mocks the daemon for every scenario; the website preview uses it too), and the gallery machinery itself under packages/ui/src/gallery/, the gallery's pages and its scripts in packages/ui/scripts/.
  • App preview: gallery only.
  • Preview scratch location: packages/ui/src/gallery/preview/ (ignored by git, so per checkout). Each .ts / .tsx file directly in it default-exports a Scenario[] that packages/ui/src/gallery/fixtures/index.ts appends to the catalog, so it must also pass the gallery's tests; it imports fixtures from their own modules, never from that index.ts (a cycle). Temporary mocks and helpers go in preview/mocks/, which the loader does not read. The record of services the preview started goes in preview/services.md.
  • Scenarios verify the UI, not each piece of copy. The same UI with different copy does not get another scenario, nor does a different value of a form control (select, switch, radio, segmented control, text field): one scenario shows the UI, and where the other copy or values are worth asserting, a test does it. A value or a piece of copy is a scenario of its own only where it changes the layout, such as the longest option label that must still fit. Error scenarios are merged only where the message has the same format and layout and differs only in values or wording; where the copy's format or layout differs (one line against several, a details block, a list, a long unbroken path, a title against none), or the actions offered differ (a different set of buttons), they stay separate scenarios. In this project this narrows .claude/agents/gallery-writer.md's "Scenario standard": under "The number of mocks does not decide the number of scenarios", targets that differ only in copy or a control's value are not split even where showing one replaces the other, and being able to switch between them does not make them separate views; and "Viewing conditions do not get their own scenarios" extends beyond the gallery's own viewing controls to copy and form-control values. (Source: user instruction)
  • Viewing conditions: in this project this narrows .claude/agents/gallery-writer.md's "Scenario standard", under "Viewing conditions do not get their own scenarios". A layout that differs under a condition is what the gallery's viewing controls are for: the scenario that shows the state points at the condition in its description. Steps are written to run under whatever condition the controls pick, so no copy is made just to reach a control under it. A condition is fixed in the scenario only where the confirmation target cannot be reached by choosing that condition with the controls on another scenario, with the title or description saying why.
  • Quick check scope and handling: this sets what the quick check covers and how a failure is handled; when it runs is set by CLAUDE.md's "This project", not here. In this project this narrows "Quick check failure" below and .claude/agents/gallery-writer.md's "Finishing" where they differ. (Source: user instruction)
    • What it guards: the gallery, not the app, whose correctness is for type checking and the tests.
    • What it covers: the scenarios gallery-writer wrote into the gallery and the scenarios previewed for the user, by id ("Quick check (selected scenarios)"); scenarios that already passed are not rerun unless this change has changed since. Of what was written into the gallery, only the scenarios added or changed, and the full check when something many scenarios use was changed, since which scenarios it reaches cannot be told from the ones changed ("What many scenarios share" lists only the known part and is not the limit).
    • Conditions: only the source language (en) and the light theme; a scenario that fixes a language or theme runs under its own condition. Whether language-dependent things are right (translations complete, formats correct, a scenario's steps finding their controls in other languages) belongs to type checking and the tests, and what can be written as a script check does not rely on rendering several languages. Other languages and themes are swept only when the user asks, and for a subagent that means what whoever dispatched it passed on.
    • Passing and baseline failures: every scenario that runs must pass. A failure that also occurs on the baseline before the change (e.g. the branch to merge back into) is not fixed and does not block delivery; state in the final reply that it failed before the change and does not count as passing. Verify the baseline in a separate copy, isolated from other checkouts as the "Opening the gallery" column says and removed after use, leaving this working copy alone.
    • Rerun and final reply: once a failure is fixed, whoever fixed it reruns the scenarios that failed, by id, until they pass. State in the final reply whether the full check, which scenarios, or none were run, and the result.
  • gallery-writer also runs the project's type check and the relevant tests, and before starting runs the checks it will run at the end on the range it is about to change, noting the failures that already exist. A failure its change caused it fixes within what it owns; one that cannot be removed, that predates its change, or that is the app's behaviour being wrong it does not fix: it keeps its change and reports the failure with whose it is, marked uncertain where it cannot tell. In this project this narrows .claude/agents/gallery-writer.md's "Finishing". (Source: user instruction)

Changing the gallery

  • Dispatch the gallery-writer subagent for every write to formal scenarios, mocks and the gallery machinery; with a subagent mechanism, write none of it yourself (without one, see the last item): dispatch it for a new or changed UI state, or a change to the interface contracts and types mocks depend on (even if the UI did not change); how a scenario is shown, which to extend and which to delete, is its judgement.
  • One dispatch at a time, to keep each from adding its own; it cannot see your conversation, so each time hand over every UI state to be shown, what each is for a person to confirm, what changed in the contract, the files this change touches and the trade-offs the user settled, plus the address of any preview this working copy is serving.
  • For what it reports as unshowable, needing app code changes, or trade-offs it could not settle: decide the minor ones yourself and leave the rest to the user; where the conventions must follow, handle it as "Project conventions" says.
  • The subagent this skill dispatches is installed with it: with a subagent mechanism but no definition of the one to dispatch, the install is incomplete: stop and ask the user to rerun the installer that installed this skill. Without a subagent mechanism, read the installed definition and do the work by its rules yourself.

Quick check failure

  • Pass only by making things right: never delete scenarios, skip or loosen checks to make it pass, and never change a scenario or mock to accommodate an app error.
  • Every failure gets fixed, by cause: where the app code is wrong, change the app code; where a scenario, mock or the gallery machinery is broken or behind, dispatch gallery-writer to fix it, and delete a scenario only where its UI state no longer exists in the app.
  • Passing the check only shows the scenarios run, not that they show the latest UI: where appearance and interaction need confirming, look at them for real.

Previewing for the user to confirm

  • When this change touches the UI, give the user a preview: where whether it is right takes a human eye, wait for confirmation before delivering; where the user has already given the result and nothing needs judging (such as reordering, or changing one piece of copy), give the entry only and do not wait.
  • Start the gallery from this task's branch or working copy, with the app preview where needed, avoiding other working copies as the conventions say; never borrow a service running elsewhere, which does not show this branch's changes.
  • Give each view to confirm a direct entry: written as the convention's "Scenario direct entry", with the viewing conditions, using the actual address after start; open it yourself first to confirm it shows this branch's changes; one you cannot open yourself (such as a build on a real device) is given anyway, saying you could not confirm it.
  • If no usable preview can be given, say plainly where it is stuck, and do not hand the UI change over as ready to confirm.
  • Keep the preview running while waiting for confirmation; refresh it after acting on revision requests, and give new entries where they changed.
  • Scenarios and mocks added only for the preview go into the "Preview scratch location", never mixed into the formal scenarios; when asking for confirmation, ask whether to keep them, and where you are not waiting for confirmation, still wait for the answer to this question; those to keep are handed to gallery-writer at once to be made formal scenarios.
  • Record the services you start and the builds you install in the "Preview scratch location", enough to recognise at cleanup that they are this working copy's.
  • Never overwrite, stop or uninstall a service or build not started or installed by this working copy; when unsure, treat it as not yours and report: overwriting or uninstalling a build with the same app identifier deletes its data too.

Cleanup

  • Clean up before the branch is handed over (merge, push for a PR and so on), when the user abandons the change, or before the working copy is deleted.
  • Stop the services and uninstall the builds the "Preview scratch location" records, and delete the temporary scenarios, mocks and records there; touch nothing outside it.
  • Leave alone what you cannot verify (such as a device that cannot be reached), reporting where it is and how to recognise it; tell the user what was cleared.
  • If the preview is not yet cleaned up at delivery, list in the final reply the services still running and the builds left, how to recognise them and how to clear them, so a working copy deleted directly does not leave them unrecognisable.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.