agentleFS
ainurdevainurdev/mystical-assistant/.claude/skills/design-first/SKILL.md

design-first

Skill7 starsChanged 8 days agoMITView on GitHub

Use when the user sends /design-first <task> or presses the composer's DESIGN button — design the change before any implementation. Produces brand-system HTML mockups plus a short spec, screenshots them into the transcript, pushes the draft to the linked Claude Design project, and stops for approval; repo code changes start only after the user approves.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read ~/.bridge_state/project_config.json.

    line 15

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “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

Design first, implement after approval

The argument is a UI task. Do NOT implement it yet. This skill exists to put a reviewable design in front of the user — in the transcript and in their claude.ai design pane — before any repo code changes.

1. Find the linked design project

Read ~/.bridge_state/project_config.json. The key is the repo's trailing path (this repo: /mystical-assistant), with an optional @<branch> variant that wins over the plain key; the field is design_project. No key → tell the user the repo isn't linked (dashboard ▸ the chat header's project name ▸ ◇ Design system, or SETTINGS ▸ Projects ▸ Design system), design in-chat anyway, and skip step 4.

2. Design

Load the repo's design-system skill (here: mystical-assistant-design) and design with its tokens and components — no generic styling. Deliverables go in .mystical/design-drafts/<slug>/ (git-ignored runtime state):

  • One self-contained HTML file per screen or state — inline CSS, no external fetches, first line <!-- @dsCard group="Drafts" --> so claude.ai renders it as a preview card.
  • SPEC.md — intent, components and tokens used, states, behavior notes, open questions. Short.

With the experimental switch on, use the design view instead of steps 3 to 5. Read design_context (find_tools), then call show_design. When the direction is open, make three rough directions as three pages on one board, say how they differ and ask which way to go. The user opens PREVIEW DESIGN, points, draws, tweaks and remixes, and their comments come back as a message naming the elements. Keep editing the page files: edits appear live. inspect_ui and critique_design are there for checking it. Then ask for approval, and implement after it.

3. Show it in the transcript

Screenshot each mockup with the bridge-eyes skill and include the images in your reply. The user reviews from a phone: the pictures are the review, the HTML is the backup.

Choices ride in the question, not loose in the transcript. Directions to pick between (A · TOKEN, B · HEADER…) don't get Attached one by one — that pile is what made the user match file names to letters. The crops go in step 5's question: each direction's crops in its option's preview, one markdown image per state, ![In the box](/abs/path/a1.png). The card shows them on a stage beside the options, tabbed by state. Attach only what isn't a choice: the one design up for approval, a before shot.

4. Push the draft to Claude Design

DesignSync: finalize_plan with the projectId, writes: ["drafts/<slug>/**"], localDir: <repo>/.mystical/design-drafts/<slug> → write_files using localPath per file, targeting drafts/<slug>/.... The user confirms the plan card; afterwards the draft is viewable in the claude.ai design project.

5. Stop for approval

AskUserQuestion. Several directions: one option per direction (up to three), lettered (A · TOKEN, the one you recommend first), its crops in preview, plus Park it; revising is the card's own free-text answer. One design: Approve & implement (its crops in that option's preview) / Revise (they say what) / Park it. Do not touch repo code before an approve. On revise, loop back to step 2. On approve, implement with the mockups and SPEC.md as source of truth, normal workflow. After it ships, offer once to promote the draft into the design system proper or delete drafts/<slug>/ remotely — never do either silently.

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.