Compress agent skills
This commit is contained in:
@@ -6,212 +6,46 @@ compatibility: opencode
|
||||
|
||||
# UI Variations
|
||||
|
||||
Use this skill when the user wants help exploring UI directions for a new or existing web UI surface and wants real code, not static mockups.
|
||||
Use when the user wants real coded UI directions for a web UI surface, not static mockups.
|
||||
|
||||
This skill is optimized for browser-based apps first. Favor in-app previews that reuse the real design system, routing, and data flow. Fall back to an isolated preview page only when the target repo makes in-situ previewing awkward or risky.
|
||||
## Defaults
|
||||
|
||||
## Default Behavior
|
||||
- Ask at most one clarification if the target surface is unclear.
|
||||
- Inspect repo docs, routing, components, styling, and design-system primitives before editing.
|
||||
- Generate 3-5 materially different variations of only the requested surface.
|
||||
- Present one active variation at a time with a floating bottom-centered switcher.
|
||||
- Keep the previewed UI production-ready; do not render rationale or experiment notes inside it.
|
||||
- Stop at preview by default. If the user picks a winner, integrate it and remove preview-only artifacts.
|
||||
|
||||
- Ask at most one short clarification if the target page, component, or feature area is unclear.
|
||||
- Inspect the repository before editing. Look for design philosophy docs, design-system conventions, router structure, and existing component primitives.
|
||||
- Only create variations of the UI surface the user asked for. Keep the rest of the page and surrounding experience stable unless the user explicitly asks for broader exploration.
|
||||
- Generate 3-5 materially different variations.
|
||||
- Present one variation at a time on a single preview surface.
|
||||
- Add a floating bottom-centered variant switcher so the user can compare directions quickly.
|
||||
- Make each variation look production-ready. Do not present wireframes, placeholder framing, or experiment-looking chrome unless the user explicitly asks for that level of fidelity.
|
||||
- Keep rationale out of the UI itself. Do not render explanatory labels, design notes, or variation descriptions inside the previewed interface.
|
||||
- If the `agent-browser` skill is available and the app can run locally, use it to visually inspect the rendered variants and refine obvious issues before asking the user to choose.
|
||||
- Stop at the preview phase by default.
|
||||
- If the user later picks a winner, fully integrate that choice and remove the preview-only artifacts.
|
||||
## Preview Mode
|
||||
|
||||
## Inputs
|
||||
1. Discover local UI language using `references/discovery-checklist.md`.
|
||||
2. Choose the smallest honest preview surface: real feature/page, internal preview route, then isolated sandbox as fallback.
|
||||
3. Build variations that differ in hierarchy, density, framing, action emphasis, typography, navigation, or control presentation.
|
||||
4. Reuse the same content/data across variants and preserve surrounding page behavior.
|
||||
5. Add a bottom-centered switcher with labels like `A`, `B`, `C`, visible active state, pointer-friendly controls, and mobile-safe placement.
|
||||
6. Keep preview-only code grouped and easy to delete.
|
||||
7. Run focused lint/typecheck/test/build checks available in the repo.
|
||||
8. If the app can run and `agent-browser` is available, inspect desktop and mobile rendering and refine obvious visual issues.
|
||||
9. Report preview route, files changed, variant labels with one-line rationale, and known gaps. Use `templates/preview-summary-template.md` when useful.
|
||||
|
||||
The skill can usually infer most of these from the repo. Only ask when a missing answer would block safe progress.
|
||||
## Promotion Mode
|
||||
|
||||
| Input | Default | Ask only if needed |
|
||||
|-------|---------|--------------------|
|
||||
| Target UI surface | Infer from user request and repo structure | Yes |
|
||||
| Number of variations | 4 | No |
|
||||
| Preview surface | In-situ when practical, isolated when necessary | No |
|
||||
| Device emphasis | Existing repo defaults | No |
|
||||
| Promotion behavior | Wait for user selection | No |
|
||||
When the user selects a winner:
|
||||
|
||||
## Workflow
|
||||
1. Move the winning variation into the real production surface.
|
||||
2. Rename experiment code so it reads like normal app code.
|
||||
3. Update imports, tests, stories, snapshots, and callers as needed.
|
||||
4. Remove preview route, switcher, losing variants, temporary helpers/fixtures, dead styles, and orphaned assets.
|
||||
5. Verify the final integrated surface, not just the preview.
|
||||
6. Report winner, integration location, removed artifacts, and checks run.
|
||||
|
||||
The work has two modes: preview mode and promotion mode.
|
||||
|
||||
### Preview Mode
|
||||
|
||||
#### 1. Discover the local UI language
|
||||
|
||||
Read the minimum necessary files to understand the app before editing:
|
||||
|
||||
- project docs such as `README*`, `docs/**`, `CONTRIBUTING*`, or design notes
|
||||
- router and layout entry points
|
||||
- component primitives, shared wrappers, and design tokens
|
||||
- styling setup such as Tailwind config, CSS variables, theme providers, or UI libraries
|
||||
- existing patterns for feature previews, internal-only routes, or story/demo pages
|
||||
|
||||
Use `references/discovery-checklist.md` as the discovery checklist.
|
||||
|
||||
#### 2. Choose the preview surface
|
||||
|
||||
Prefer the smallest correct surface:
|
||||
|
||||
- Best: preview the ideas inside the real feature/page so spacing, layout, and surrounding context stay honest.
|
||||
- Acceptable: add a preview route or internal page that still uses the app's real shell.
|
||||
- Fallback: add an isolated sandbox page if the app architecture makes in-situ previewing expensive.
|
||||
|
||||
If you add a dedicated preview route, follow local router conventions and use a clearly temporary path such as `/_ui/...`, `/internal/...`, or the repo's existing preview pattern.
|
||||
|
||||
#### 3. Build the variations
|
||||
|
||||
Create 3-5 variations that differ in meaningful ways, not just color or copy tweaks.
|
||||
|
||||
Only vary the requested surface. Do not add extra sections, side quests, marketing panels, helper callouts, or new feature ideas unless they are already part of the requested UI or the user explicitly asks for broader exploration.
|
||||
|
||||
Aim to vary things like:
|
||||
|
||||
- information hierarchy
|
||||
- density and spacing
|
||||
- framing and container treatment
|
||||
- interaction emphasis and primary actions
|
||||
- typographic rhythm
|
||||
- navigation or control presentation
|
||||
|
||||
Keep the comparison fair:
|
||||
|
||||
- reuse the same content and data across all variations
|
||||
- keep functional behavior as constant as possible
|
||||
- share supporting data fixtures/helpers when that reduces duplication
|
||||
- do not invent a new design system when the repo already has one
|
||||
- do not put variation names, rationale text, or design commentary inside the UI itself
|
||||
- make the UI feel shippable rather than like a design exercise
|
||||
|
||||
#### 4. Build the switcher
|
||||
|
||||
The preview must include a floating switcher anchored at the bottom center of the screen.
|
||||
|
||||
The switcher is the only comparison control that should visibly describe the variants. Keep the previewed UI itself clean and presentation-ready.
|
||||
|
||||
Requirements:
|
||||
|
||||
- one active variation at a time
|
||||
- clearly labeled variants such as `A`, `B`, `C`, `D`
|
||||
- visible active state
|
||||
- pointer-friendly controls
|
||||
- mobile-safe placement
|
||||
- use local app styling rather than foreign widget styling
|
||||
|
||||
Nice to have when cheap:
|
||||
|
||||
- previous/next controls
|
||||
- keyboard shortcuts
|
||||
- query param or route state so the active variation is easy to share or refresh
|
||||
|
||||
#### 5. Keep the preview removable
|
||||
|
||||
Structure preview code so cleanup is straightforward after the user picks a winner.
|
||||
|
||||
Good patterns:
|
||||
|
||||
- keep preview-only components grouped in one local folder
|
||||
- keep variant selection state local to the preview surface
|
||||
- isolate temporary wrappers and comparison helpers from production code paths
|
||||
|
||||
Avoid building a permanent preview framework unless the repo already has one.
|
||||
|
||||
#### 6. Verify
|
||||
|
||||
Run the lightest relevant checks available in the target repo.
|
||||
|
||||
- validate changed files with the repo's normal lint, typecheck, or test commands when practical
|
||||
- run a focused dev/build check if the app supports it
|
||||
- if a local app can run and `agent-browser` is available, use it to confirm the preview route renders and the switcher works
|
||||
- verify desktop and mobile layout if the surface is responsive
|
||||
|
||||
#### 7. Refine visually before handoff
|
||||
|
||||
If `agent-browser` is available, prefer one refinement pass before asking the user to choose.
|
||||
|
||||
- open the preview in the browser and inspect the rendered result rather than trusting code alone
|
||||
- use visual inspection and available vision capabilities to catch awkward spacing, weak hierarchy, cramped mobile layouts, clipping, contrast issues, or component mismatches
|
||||
- make targeted refinements so each variation looks polished and production-ready
|
||||
- keep the refinements scoped to the requested surface rather than adding extra UI the user did not ask for
|
||||
|
||||
If `agent-browser` is not available, skip this step and hand off after normal code-level verification.
|
||||
|
||||
#### 8. Hand off for review
|
||||
|
||||
When the preview is ready, report:
|
||||
|
||||
- preview route or entry point
|
||||
- files changed
|
||||
- the variant labels and one-line rationale for each
|
||||
- any known compromises or gaps
|
||||
|
||||
Use `templates/preview-summary-template.md` as the output structure when useful.
|
||||
|
||||
### Promotion Mode
|
||||
|
||||
When the user selects a winning variation, do not leave the repo in a "choose later" state. Finish the job.
|
||||
|
||||
#### 1. Promote the winner
|
||||
|
||||
- move the winning variation into the real production surface
|
||||
- preserve the chosen layout, hierarchy, and interaction details
|
||||
- adapt naming so the final code reads like normal app code, not experiment code
|
||||
- update imports, tests, stories, snapshots, and callers that depend on the old structure
|
||||
|
||||
#### 2. Remove the temporary comparison layer
|
||||
|
||||
Delete or collapse preview-only artifacts that are no longer needed:
|
||||
|
||||
- preview routes or sandbox pages
|
||||
- variant switcher UI
|
||||
- losing variants
|
||||
- temporary helpers, fixtures, and wrappers that only existed for comparison
|
||||
- stale imports, dead styles, and orphaned assets
|
||||
|
||||
#### 3. Verify the final integrated result
|
||||
|
||||
- run the relevant checks again
|
||||
- if the app can run locally, verify the real surface rather than only the preview route
|
||||
- confirm no preview-only controls remain visible in the integrated experience
|
||||
|
||||
#### 4. Report completion
|
||||
|
||||
Summarize:
|
||||
|
||||
- which variation won
|
||||
- where it was integrated
|
||||
- which temporary artifacts were removed
|
||||
- which checks were run
|
||||
|
||||
Use `references/promotion-checklist.md` as the final cleanup checklist.
|
||||
Use `references/promotion-checklist.md` for cleanup.
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Favor the app's real primitives, spacing system, tokens, and layout patterns.
|
||||
- Make the smallest change set that still yields meaningfully different ideas.
|
||||
- Limit changes to the user-requested surface unless broader page changes were explicitly requested.
|
||||
- Do not overwrite unrelated work or refactor broadly just to host the preview.
|
||||
- Keep each variation honest to the product's existing brand and interaction model unless the user explicitly asks for something more radical.
|
||||
- Do not embed design explanations, variant descriptions, or self-referential experiment text inside the UI.
|
||||
- Make the preview look production-ready enough that the chosen variation can be promoted with minimal cleanup.
|
||||
- If visual browser inspection is available, use it to polish the variants before requesting user feedback.
|
||||
- Do not stop at mockups once the user has chosen a direction. Integrate the winner and clean up the rest.
|
||||
- Prefer code that is easy to delete or fold into production cleanly.
|
||||
|
||||
## References
|
||||
|
||||
| Reference | Purpose |
|
||||
|-----------|---------|
|
||||
| `references/discovery-checklist.md` | What to inspect before editing |
|
||||
| `references/promotion-checklist.md` | What to remove and verify after a winner is chosen |
|
||||
|
||||
## Templates
|
||||
|
||||
| Template | Purpose |
|
||||
|----------|---------|
|
||||
| `templates/preview-summary-template.md` | Concise handoff summary for the preview phase |
|
||||
- Favor the app's real primitives, tokens, spacing, layout, and interaction patterns.
|
||||
- Do not broaden scope beyond the requested surface unless explicitly asked.
|
||||
- Do not create a permanent preview framework unless the repo already has one.
|
||||
- Do not overwrite unrelated work or refactor broadly to host the preview.
|
||||
- Make each variation shippable enough that the winner can be promoted with minimal cleanup.
|
||||
|
||||
Reference in New Issue
Block a user