Skill commands and reference guidance
The Impeccable skill turns a design request into a bounded workflow. Command metadata describes the available actions. Executable helpers provide shared support. Reference guides define the design decision, evidence, and handoff rules for work such as onboarding, polishing, shaping, and routing.
This page is a child of Agent design workflows. Related guidance covers live editing sessions, agent hooks and edit interception, design context and critique, and AI provider integration.
Command surface
Command catalogue
The command catalogue is the user-facing map of design work. Command metadata gives hosts a short description and argument hint. The matching reference guide defines the work and its boundary.
| Category | Design question | Commands |
|---|---|---|
| Build | What should exist and what direction should it take? | craft, shape, init, document, extract |
| Evaluate | What quality or experience problems exist? | critique, audit |
| Refine | How should an existing surface improve without changing its purpose? | polish, bolder, quieter, distill, harden, onboard |
| Enhance | Which visual quality needs focused work? | animate, colorize, typeset, layout, delight, overdrive |
| Fix | Which clarity, context, or performance problem needs correction? | clarify, adapt, optimize |
| Iterate | Which live or generated alternatives should the user compare? | live, generate |
The catalogue also records special paths. craft is a deprecated alias for ordinary new work, and teach aliases init. Native targets use native references where available. Web adapt and audit switch to native guidance for native projects. live, generate, and the bundled detector are web-only. Android work follows Material rules and uses emulator or device evidence instead of browser captures.
References: plugin/…/SKILL.md• L43-70 plugin/…/command-metadata.json• L1-94 plugin/…/adapt.md• L1-5 plugin/…/audit.md• L1-5 plugin/…/audit.native.md• L1-4 skill/…/android.md• L1-5 skill/…/android.md• L42-46
Command execution
The launcher is the stable entry point for command support. A session loads project context once from the skill directory. Each selected command then uses that context and its own reference instead of rebuilding the project picture. Executable helpers collect context, store records, detect issues, serve review pages, or manage live sessions. The reference guide remains the authority for design judgment.
The launcher selects a compatible engine for the skill version and platform. It prefers an explicit operator choice or a verified bundled or cached engine. If setup needs network access or a writable cache, the launcher reports that boundary instead of running an unverified engine. A compatible preinstalled engine remains usable when the environment cannot download one.
Live support is a separate local interactive path. It resolves the app root, serves the selected page through a development server or static file, and keeps the browser preview tied to the selected element and session. The agent generates or inserts variants, and the user accepts or discards the result. Accepted work is written to true source; temporary preview state is removed before completion. Session journals and recovery commands protect active work across helper restarts. A failed mount stays visible until retry, a successful mount, or a new cycle.
References: plugin/…/SKILL.md• L17-23 plugin/…/SKILL.md• L80-88 skill/…/impeccable• L76-91 skill/…/impeccable• L109-152 skill/…/impeccable• L154-265 skill/…/impeccable.cmd• L1-23 skill/…/live-browser.js• L16-32 skill/…/live-browser.js• L105-132 skill/…/live-browser.js• L197-218 skill/…/live-browser.js• L233-273 plugin/…/live.md• L3-20 plugin/…/live.md• L72-82 plugin/…/live.md• L277-299 plugin/…/live.md• L327-341
Command routing
Explicit command routing
An explicit command selects one workflow. The agent reads that command's reference and follows its contract. Native targets use a native variant when the platform needs one. If two commands fit, the agent asks once instead of silently combining their scopes.
The routing rules preserve a key boundary: shape owns discovery and enters new-work only for visual-world or surface-concept decisions. A narrow refinement stays on the existing implementation. A new surface or replacement visual world enters new-work.
References: plugin/…/SKILL.md• L72-80 plugin/…/shape.md• L37-39 plugin/…/new-work.md• L1-5
No-argument routing
An invocation with no argument means “what should I do?” The routing guide uses project signals to present two or three useful recommendations and then shows the full command menu. It waits for the user's choice. It never runs the lead recommendation automatically.
The recommendations reflect the current project state. Missing product context can lead to init. Missing design documentation can lead to document. A weak or absent critique can lead to critique or polish. Changed files can narrow the target. A running web server can make live or generate available. Native projects stay out of browser and HTML-detector recommendations.
This diagram shows how a bare invocation becomes a user-selected workflow.
flowchart LR
A[No-argument request] --> B[Load session context]
B --> C[Read project signals]
C --> D[Run useful web detection when allowed]
D --> E[Recommend focused commands]
E --> F[Show full menu]
F --> G[User selects a command]
G --> H[Load its reference guide]
References: plugin/…/SKILL.md• L72-78 plugin/…/routing.md• L7-24
Reference guide system
Workflow ownership
Each command guide owns one kind of decision. This keeps a technical audit from becoming a design review, a polishing pass from becoming a redesign, and a context change from becoming simple scaling.
| Guide | Owns | Stops or hands off at |
|---|---|---|
init | Durable product context | Product truth in PRODUCT.md |
document | The current visual system and its reusable guidance | A confirmed DESIGN.md and sidecar, or an honest seed before implementation |
onboard | First value, empty states, and feature discovery | A usable path to the product's first useful moment |
shape | Discovery and a confirmed brief | Confirmation before code or persistence |
new-work | New surfaces and replacement visual worlds | A recorded direction ready for its chosen build path |
polish | Bounded refinement of the incumbent surface | A finished path with current evidence addressed |
distill | Removal of excess while preserving necessary function | A simpler path with required information and access intact |
quieter | Lower visual intensity without losing hierarchy or personality | A restrained surface that remains clear and distinctive |
overdrive | User-chosen enhancement to how an interface feels | A verified enhancement with a useful fallback and controlled cost |
critique | Independent design and evidence assessment | A persisted snapshot, synthesis, and user-directed next step |
audit | Report-only technical quality review | Findings routed to commands that can fix them |
optimize | Measured performance improvement | A verified change against the observed bottleneck |
harden | Resilience under real data and failure conditions | Evidence across boundary states and environments |
adapt | Experience changes for a new context rather than simple scaling | Verification on the target device, input, or platform |
visualize | Composition options after the world is fixed | One approved composition for the build |
hooks | Project detector-hook state and finding triage | A configured hook or a clear user decision on an exception |
doctor | Drift between installed artifacts and current skill expectations | Mechanical repair, a named truth gap, or a user decision |
The guide is the authority for behavior. Executable helpers can collect context, store records, detect issues, or serve a review. They do not replace the guide's design judgment.
References: plugin/…/SKILL.md• L43-70 plugin/…/critique.md• L1-16 plugin/…/audit.md• L1-5 plugin/…/document.md• L1-3 plugin/…/document.md• L64-80 plugin/…/distill.md• L1-3 plugin/…/overdrive.md• L8-20 plugin/…/quieter.md• L1-10 skill/…/audit.md• L1-5 skill/…/doctor.md• L1-12 skill/…/optimize.md• L1-2 plugin/…/visualize.md• L1-5
Design critique
critique separates design judgment from deterministic evidence before it combines them. On web targets it uses an independent design assessment and detector or browser evidence. Native targets use design review only because the web detector does not apply. The command then produces one critique with a design health score, priority issues, persona risks, and questions tied to the findings.
The chat report is the primary result. A target-specific snapshot preserves the assessment for later work, and polish can use its current priority issues. The run closes with targeted user questions when enough issues exist, or with an explicit skipped-questions reason.
References: plugin/…/critique.md• L1-16 plugin/…/critique.md• L31-46 plugin/…/critique.md• L48-63 plugin/…/critique.md• L65-99 plugin/…/critique.md• L101-139 plugin/…/critique.md• L204-240 plugin/…/critique.md• L242-264
Technical audit
audit is a report-only technical review for web projects. It measures accessibility, performance, theming, responsive behavior, and implementation integrity, then scores each dimension and assigns severity to verified findings. Native projects use the native audit path instead of browser or HTML evidence.
The audit does not fix the surface. It records an overall health score, concrete findings with impact and locations, positive findings, systemic patterns, and commands that can address the problems. It saves the report after delivery so later work can use the findings without replacing the user-facing report.
References: plugin/…/audit.md• L1-9 plugin/…/audit.md• L11-22 plugin/…/audit.md• L24-71 plugin/…/audit.md• L73-86 plugin/…/audit.md• L88-113 plugin/…/audit.md• L124-157
Design documentation
document records the visual system that later agents must preserve. In scan mode it extracts real tokens and component patterns, then confirms the descriptive language. The root DESIGN.md carries the normative token layer and canonical visual sections. The .impeccable/design.json sidecar carries extensions such as tonal ramps, motion, breakpoints, component snippets, and narrative that the token format cannot hold. The sidecar extends the frontmatter rather than duplicating its token primitives, and its component snippets are meant to render as self-contained panel examples.
Seed mode is for a project with no visual system to extract. It first requires product context and uses the new-work world choice to write a directional seed. The seed records durable direction with honest unresolved implementation facts; it has no fabricated component tokens or sidecar. A later scan mode run replaces that provisional view with the observed system.
The command must not silently overwrite an existing DESIGN.md. It shows the current file and waits for a refresh, overwrite, or merge choice. On a new seeded world, the first build writes the durable design record from the shipped result rather than defending a pre-build guess.
References: plugin/…/document.md• L1-3 plugin/…/document.md• L43-62 plugin/…/document.md• L64-80 plugin/…/document.md• L96-116 plugin/…/document.md• L253-257 plugin/…/document.md• L305-326 plugin/…/document.md• L352-385
Direction selection
new-work decides whether a surface inherits the current visual world, extends it, or replaces it. A missing DESIGN.md does not by itself mean the project is greenfield. The guide checks the product code, tokens, components, assets, and confirmed brand commitments before it chooses the level of invention. A local addition inherits an established surface instead of starting a new identity exercise.
For a new surface inside an established world, the concept-seed step presents a small set of composition choices. The assigned option is the rolled lead. Other dealt structures and catalog challengers retain clear identities so the decision page and later build steps report the same choice. For a new or replacement visual world, the direction round compares grounded candidates and challengers. The user still chooses the direction.
The direction choice also selects the build route for the session. A code-led route carries its ambition in the direction contract. A comp-led route turns an approved composition into a measured build contract. The route does not change who owns product truth or the user's authority over the direction. Before code, the chosen direction is recorded in a surface brief as a development-only contract. It guides the build and review but never enters source or browser output.
References: plugin/…/new-work.md• L1-17 plugin/…/new-work.md• L30-42 plugin/…/new-work.md• L44-50 plugin/…/new-work.md• L62-68 plugin/…/new-work.md• L70-80
Product onboarding
init captures confirmed product truth in the resolved PRODUCT.md so later work has a durable source for users, purpose, capabilities, constraints, platform, and evidence. It does not create a visual world or write DESIGN.md. It can record a build-path default and configure live mode for a runnable web project. Before later shaping or building resumes, PRODUCT.md must exist at the resolved path and contain the product record.
onboard has a different goal. It moves an existing user to first value through a real product path, using examples, empty states, or small hints where needed. It keeps advanced teaching for later discovery and allows a skip path when possible. A project can need product context, a better first-run path, or both. Neither command should silently take over the other's job.
References: plugin/…/init.md• L1-15 plugin/…/init.md• L17-23 plugin/…/init.md• L25-56 plugin/…/init.md• L58-110 plugin/…/init.md• L112-135 plugin/…/onboard.md• L1-4 plugin/…/onboard.md• L28-57 plugin/…/onboard.md• L168-193
Surface shaping
shape resolves what a surface must do before implementation begins. It asks about the audience, outcome, content, states, scope, interaction, and constraints. It returns the smallest useful brief and waits for confirmation.
The brief is a handoff, not a build artifact. It keeps unresolved product choices out of code. Confirmed work can then continue into new-work or another scoped command without reopening settled discovery.
References: plugin/…/shape.md• L3-14 plugin/…/shape.md• L25-35 plugin/…/shape.md• L41-59
New visual work
new-work protects the boundary between product truth, visual authority, and surface strategy. It records the chosen direction in a development-only contract before code. That contract guides the build and review but must not enter source code or browser-delivered output.
The build path changes how the chosen direction becomes a surface. Comp-led work uses an approved composition as a measured reference and moves through gates for composition, measurement, assets, the first viewport, later sections, motion, and responsive behavior. Code-led work skips the comp round by contract and carries its ambition in the direction contract. Both paths inspect the result and finish with review and documentation. A new or replacement visual world is not complete until its shipped result produces the durable design record.
References: plugin/…/new-work.md• L1-5 plugin/…/new-work.md• L48-50 plugin/…/new-work.md• L62-68 plugin/…/new-work.md• L80-106 plugin/…/new-work.md• L105-125
Composition review
Comp-led work has a human checkpoint before page code exists. When a surface round already showed a locked decision comp, that comp discharges the three-option round. Otherwise visualize produces three composition options after the visual world is fixed. The user approves, revises, combines, rejects, or delegates the choice. The selected comp then becomes the build reference.
This round tests composition, narrative, hierarchy, density, focal use, and image needs. It does not reopen the visual identity. Core text, controls, responsive behavior, accessibility, semantics, and interaction states remain implementation work. After approval, the comp becomes a measured reference rather than a poster to copy.
References: plugin/…/visualize.md• L1-5 plugin/…/visualize.md• L7-23 plugin/…/visualize.md• L25-39
Interface polishing
polish improves an existing interface without replacing its visual world, content, behavior, or out-of-scope areas. It treats rendered use and the real interaction path as evidence. Detector findings and a current critique snapshot help locate work, but neither proves that the surface is good. A critique snapshot is used only while its target remains current; an independent pass still checks the complete path.
distill is a narrower form of refinement. It removes redundant content, visual noise, excess choices, and cosmetic complexity while preserving the user's primary goal, necessary information, accessibility, and required function. quieter reduces intensity while keeping hierarchy and personality. These paths end by checking that the result remains complete and easier to use.
References: plugin/…/polish.md• L1-5 plugin/…/polish.md• L7-35 plugin/…/polish.md• L37-47 plugin/…/polish.md• L49-83 plugin/…/polish.md• L85-105 plugin/…/distill.md• L1-3 plugin/…/distill.md• L94-111 plugin/…/quieter.md• L5-10 plugin/…/quieter.md• L46-99
Live command setup
live changes an existing local page in an interactive loop. It requires a running development server with HMR or a static local page. The startup path resolves the app root and page to open, can create the common local configuration, and reports missing pages or configuration drift instead of making an unclear change. It never injects into deployed production sites or weakens production CSP.
Live mode is for local work only. The browser selects an element, the agent generates or inserts variants, and the user accepts or discards the result. Accepted work is written back to true source. Temporary wrappers, staged styles, and carbonize blocks are removed before the session is complete. The poll loop handles generation, steering, acceptance, discard, manual edits, mount failures, and exit. Session journals and resume commands make an interrupted session recoverable without asking the user to repeat a choice.
This diagram shows the high-level live loop.
sequenceDiagram
participant U as User
participant B as Browser
participant H as Live helper
participant S as Project source
U->>H: Start live session
H->>B: Mount picker and session bar
U->>B: Pick element and request change
B->>H: Send event and context
H->>S: Stage variants or source preview
S-->>B: Hot-swap preview
U->>B: Accept or discard
B->>H: Resolve choice
H->>S: Persist accepted source or remove staging
References: plugin/…/live.md• L3-20 plugin/…/live.md• L32-50 plugin/…/live.md• L54-70 plugin/…/live.md• L72-82 plugin/…/live.md• L256-299 plugin/…/live.md• L327-341
Asset and visual provenance
Comp-led work treats the approved composition as a reference for a semantic, responsive, accessible surface. Painted regions become produced assets. Each shipping raster carries its generation prompt or source origin so later review can tell what the asset represents and why it exists.
The reference is never silently flattened into a screenshot. UI text and controls remain live product content. This keeps the visual decision, the user experience, and the final implementation connected without making the comp itself the product.
References: plugin/…/visualize.md• L35-47 plugin/…/new-work.md• L80-106
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the skill command table, metadata, argument hints, aliases, native variants, and pin validation aligned.
- Keep no-argument recommendations user-controlled. Do not let signal collection or web detection become automatic command execution.
- Keep
live,generate, and detector recommendations out of native routing. Keep browser assumptions out of native guides. - Keep
document's scan and seed paths distinct. A seed must remain honest about missing implementation tokens and must not overwrite an existing design record without consent. - Keep DESIGN.md as the normative token record and .impeccable/design.json as its extension layer. Regenerate them together when the visual system is regenerated.
- Keep sidecar component examples self-contained and aligned with the frontmatter token names. Do not move sidecar-only extensions into the frontmatter schema.
- Keep
adapttied to the target context and gesture evidence. Do not let resized screenshots stand in for touch verification. - Keep
audit's web and native dimensions, report skeleton, severity tags, and command recommendations aligned without mixing their evidence sources. - Keep
critique's independent assessments, provenance banner, applicable score maximum, snapshot metadata, trend, and final question or skip line aligned. - Keep
shapeplanning-only and keeponboardfocused on first value rather than product setup. - Keep
initlimited to confirmed product truth and its workflow setup. Require the resolved PRODUCT.md before later shape or build work. - Keep the direction contract in the surface brief and out of implementation source or browser-delivered output.
- Keep comp-led work behind the current plan, asset, and approval gates. A changed spec or replaced comp needs a fresh review round.
- Keep approved compositions fixed as references. Do not replace semantic text or controls with raster content.
- Keep live setup tied to served files, development CSP consent, project-root discovery, and config-drift reporting.
- Keep live accept, discard, carbonize cleanup, and completion acknowledgement in the same session contract.
- Keep launcher engine compatibility, checksum validation, and platform-specific launcher behavior aligned.
- Keep
polishindependent from stale critique snapshots and close only the snapshot whose current findings it clears.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The command table, metadata, and shortcut validation disagree | A host exposes a command that does not route or pin correctly | Update the command surface and its presentation metadata together |
| A bare invocation runs its recommendation without user choice | The session starts with an unconfirmed scope | Show the focused menu and wait for the user's command |
| Web detection or live mode is offered for a native target | The menu reports tools that cannot inspect the target | Gate browser-only paths by platform |
| A critique runs both assessments in one context without declaring degradation | Design judgment can be anchored by detector output and the run appears more independent than it was | Use isolated assessments when available and emit the required method or degraded banner |
| A critique skips the final question or explicit skip line | The report has no valid close and cannot capture the user's next priority | End with targeted questions or Questions skipped: <reason> |
| A critique snapshot is treated as current after the target changes | Polish follows stale findings and may close the wrong backlog | Retain and verify the snapshot identity and current content fingerprint |
| An audit fixes issues instead of reporting them | Findings lose their independent evidence and the wrong command boundary owns the change | Keep audit report-only and route fixes to named commands |
document treats a missing DESIGN.md as permission to invent a new world | Existing visual identity is lost or a seed claims false implementation facts | Scan first, use seed mode only when no system exists, and keep seed values provisional |
document overwrites an existing design record without asking | Confirmed visual guidance is lost | Show the current record and wait for refresh, overwrite, or merge choice |
| A new-world build skips direction choice or writes code before the direction is recorded | The build falls back to an unreviewed category default | Run concept-seed, record the direction contract, and keep it out of shipped output |
| A comp-led build starts without approval or a valid comp reference | The build changes composition while claiming to follow a chosen direction | Close the composition gate and record the approved comp before building |
adapt treats a context change as a width change only | Touch, navigation, content, or device constraints fail in the target context | Verify the real input method, device conditions, and custom gestures |
| A native audit uses browser captures or the web detector | Platform conformance and device behavior remain untested | Use native audit dimensions and source or device evidence |
shape writes code or persists an unconfirmed direction | Builders implement unresolved product decisions | Stop at the confirmed brief |
| A direction contract is copied into source or browser output | Private planning data becomes part of the shipped artifact | Keep the contract in the surface brief and pass it only to reviewers and documenters |
| A live session injects into deployed production files or weakens production CSP | Production behavior or security policy changes for a development helper | Use local development injection only and use detector or extension paths for production inspection |
| Live config omits served pages or ignores reported drift | Some routes cannot start a live session or receive the helper | Use the served-file list or a suitable glob and ask before changing drifted config |
| A live component mount fails and clears the session | The user loses the handle to a server session that is still active | Keep the mount error card persistent and allow retry or a new cycle |
| Carbonize cleanup is skipped after accept | Temporary wrappers, scoped rules, or markers remain in source | Complete the cleanup gate before the next poll |
| A raster lacks prompt or origin provenance | Later review cannot trace the asset's source or intent | Embed the exact generation prompt or source origin and scan shipping asset folders |
Key files
| File | Why to read it |
|---|---|
| plugin/…/SKILL.md | Canonical command table, setup contract, aliases, routing, modes, and live boundary |
| plugin/…/command-metadata.json | Compact command descriptions and argument hints used by hosts and pinned shortcuts |
skill/scripts/impeccable | Unix launcher selection, engine compatibility checks, checksum validation, and download boundary |
skill/scripts/impeccable.cmd | Windows launcher selection, engine compatibility checks, checksum validation, and download boundary |
| plugin/…/routing.md | Context-aware no-argument menu and recommendation rules |
| plugin/…/init.md | Product truth, workflow defaults, live setup, and the completion gate for later work |
| plugin/…/critique.md | Independent assessments, evidence rules, scoring, persistence, synthesis, and close contract |
| plugin/…/audit.md | Web technical quality dimensions, scoring, severity, report contract, and saved findings |
| plugin/…/document.md | Visual-system documentation, token record, sidecar, scan path, seed path, and overwrite boundary |
| plugin/…/new-work.md | Visual authority, concept direction, build-path choice, direction contract, phased build, and finish handoff |
| plugin/…/visualize.md | Composition approval, comp-to-build boundary, asset production, and raster provenance |
| plugin/…/polish.md | Evidence-led refinement, critique snapshot use, whole-path checks, and snapshot closure |
| plugin/…/live-setup.md | Live config, served-file selection, framework setup, config drift, and development CSP consent |
| plugin/…/live.md | Browser live-session contract, event loop, recovery, variant and source-edit handling, and cleanup |
| plugin/…/adapt.md | Web context adaptation, device and input concerns, and gesture evidence |
| plugin/…/audit.native.md | Native audit dimensions, platform conformance, adaptivity, and device boundary |
| plugin/…/onboard.md | First-value, empty-state, and feature-discovery guidance |
| plugin/…/distill.md | Simplification boundaries and usability checks |
| plugin/…/quieter.md | Restraint rules that preserve hierarchy and product character |
| plugin/…/overdrive.md | User choice, progressive enhancement, and verification for ambitious interaction work |