agentleFS
JuankCadavidJuankCadavid/akili-specs/.claude/skills/diagram-design/SKILL.md

diagram-design

Skill12 starsChanged 15 days agoMITView on GitHub

Trigger: diagram, diagrams, C4, Mermaid, flowchart, sequence diagram, ER diagram, state diagram, interactive diagram, Archify, diagram slot, /akili-constitution PRD/UX/TRD steps, /akili-specify architecturally significant design, /akili-archive diagram links. Fill the diagram slots of AKILI baseline and spec documents as inline Mermaid (canonical) and, only when the archify skill is available, link an interactive HTML view.

48 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use pretty-mermaid, transitions-dev and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • drafaelSkill

    pretty-mermaid

    Render beautiful Mermaid diagrams as SVG or ASCII art using the beautiful-mermaid library. Supports 15+ themes, 5 diagram types (flowchart, sequence, state, class, ER), and ultra-fast rendering.

    Also in 3 projects that use this

  • AnasX7Skill

    transitions-dev

    Production-ready CSS transitions for web apps. Use when implementing notification badges, dropdowns, modals, panel reveals, page transitions, card resizes, number pop-ins, text swaps, icon swaps, success checks, avatar group hovers, error state shakes, search/input clear, skeleton loaders, shimmer text, sliding tabs, tooltips, staggered text reveals, card hover tilt, plus-to-menu morph, accordions, toasts, like buttons, learn-more hovers, checkbox checks, spinning counters, toggles, AI thinking states, reasoning streams, streaming text, matrix dot loaders, or banner stacking. Triggers on "add a transition", "animate the dropdown", "make the modal open smoothly", "swap icon", "page slide", "stagger animation", "open / close transition", "make it animate", "fade between", "success animation", "form error", "shake on invalid", "hover lift", "avatar stack hover", "clear the search", "skeleton loader", "loading shimmer", "shimmer text", "sliding tabs", "segmented control", "tooltip", "reveal text", "tilt card", "3D hover tilt", "cursor glare", "plus to menu", "FAB morph", "accordion", "collapsible", "expand / collapse", "disclosure", "toast", "snackbar", "like button", "heart animation", "learn more arrow", "checkbox", "check animation", "spinning counter", "odometer", "slot machine digits", "toggle", "switch", "thinking states", "AI status line", "agent reasoning", "reasoning stream", "streaming text", "stream words in", "matrix loader", "dot loader", "banner stack", "stacked toasts". Also "motion tokens", "scan for ad-hoc transitions", "replace hardcoded durations with motion tokens", "tokenize my animations", and the commands transitions reveal, transitions review, transitions apply, transitions refine.

    Also in 3 projects that use this

  • PydanticSkill

    i-have-adhd

    Shape every response for an ADHD reader who reviews the work but does not do the coding — the agent does. Use whenever responding to ANY message — coding, debugging, planning, casual. Lead with the result or the decision. Surface anything needing the user's input as a structured question, never buried in prose they'll skim past. No preamble, no recap, no closers. State errors matter-of-factly. Make finished work visible. Trigger even on casual messages and even when brevity wasn't requested.

    Also in 4 projects that use this

  • HK-hubSkill

    overdrive

    Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.

    Also in 3 projects that use this

  • AnasX7Skill

    design-taste-frontend

    Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.

    Also in 11 projects that use this

  • HK-hubSkill

    delight

    Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.

    Also in 3 projects that use this

  • +2 more from AnasX7

The file

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 45 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never load it outside these steps.

    line 28
  2. Very specific:

    Read references/slot-catalog.md at a slot step, not before.

    line 32
  3. Very specific:

    Delegate: Follow the archify skill's own authoring and delivery procedure for the slot's Archify type, with the slot's Mermaid block as …

    line 41
  4. Distinctive:

    Read the outcome from Archify's own report:

    line 48
  5. Distinctive:

    Never offer Archify's explainer mode.

    line 66
  6. Very specific:

    Never write an [archify explainer: …] line into any rules file.

    line 67
  7. Distinctive:

    Never install, update, snooze, or ignore Archify updates on your own initiative.

    line 68
  8. Distinctive:

    Use no third-party brand marks unless the user asks for them.

    line 70
  9. Very specific:

    Never state an Archify command or flag in AKILI text.

    line 71
  10. Distinctive:

    Never alter the user's Archify configuration or environment variables.

    line 72

“Common” is measured: kept by at least 6 in 10 of the 45 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

Diagram Design — Diagram Slots, Mermaid First, Interactive When Available

Every AKILI document answers its questions with named diagram slots. Each slot is an inline Mermaid block (the source of truth). When the archify skill is available, the slot also gets an interactive HTML view linked under the block. Without it, the document is still complete.

1. When to Load

Load only at these steps, each by one conditional line in the command:

CommandStepFill
/akili-constitutionStep 3 (PRD)PRD slots whose condition holds
/akili-constitutionStep 4 (UX/UI)UX/UI slots whose condition holds
/akili-constitutionStep 5 (TRD)TRD slots (C4 Context and C4 Container always)
/akili-specifyStep 2.1, architecturally significant designsdesign.md slots the change alters
/akili-archiveStep 2 (summary)List the spec's diagram links; list each baseline slot the spec's design made stale as a follow-up

Never load it outside these steps.

2. Slots

Read references/slot-catalog.md at a slot step, not before. Fill only the slots whose condition holds. A slot whose condition is false leaves nothing in the document: no empty block, no placeholder, no note. The catalog owns the conditions.

3. Mermaid First

Every filled slot is an inline fenced mermaid block in the slot's section, followed by a legend. Use the Mermaid type the catalog names. The block is the source of truth; any interactive view is derived from it. Without an interactive view, write no link line and do not state or imply that one exists.

4. Interactive View

  1. Availability, once per command run. Archify is available when the host lists an archify skill in the session, or an archify/SKILL.md exists under one of these roots: .claude/skills/, ~/.claude/skills/, .agents/skills/, ~/.agents/skills/, .opencode/skills/, ~/.config/opencode/skills/. Otherwise it is unavailable (Antigravity has no documented root, so treat it as unavailable there unless the host lists the skill). Check by reading only; never run Archify to find out.
  2. Delegate. Follow the archify skill's own authoring and delivery procedure for the slot's Archify type, with the slot's Mermaid block as input, writing to the paths below. Its SKILL.md owns every command, option, and repair rule; this skill restates none.
  3. Paths. Baseline documents: docs/diagrams/<slot-id>.json and .html, where the slot id comes from the catalog and already starts with prd-, ux- or trd- (for example docs/diagrams/trd-c4-container.json). Spec documents: docs/specs/<spec-path>/diagrams/<slot-id>.json and .html. One view per slot: on a re-render reuse the same paths, never timestamped copies.
  4. Link line. Directly under the Mermaid block, one line, exact wording: Interactive view: [<slot title>](<relative path>.html) — rendered with Archify (tt-a1i, MIT). When Archify reports its browser check as skipped, append · browser check not run.
  5. Receipts stay out of git. Archify writes sidecar receipt files beside each HTML. Ensure docs/diagrams/.gitignore and docs/specs/<spec-path>/diagrams/.gitignore exist and list *.finalize.json, *.finalize-summary.json, *.delivery.json, *.browser-check.json. Commit the slot .json and .html.

5. Outcomes and Fallback

Read the outcome from Archify's own report:

OutcomeAction
All gates passedWrite the link line
Browser check skippedKeep the HTML, write the link line with the suffix, never call the view verified
Failed after Archify's own repair limitDelete any partial output for the slot, write no link line, continue the phase; do not retry beyond that limit

Archify unavailable, or a failed delivery, never blocks the phase. The slot stands as Mermaid only. Report in one line each slot left without an interactive view and why.

6. Keep in Sync

When a slot's Mermaid block changes, re-render its view in the same run, or remove its link line and its .json and .html. A view that diverges from its Mermaid block is a defect. If Archify is unavailable in that run, remove, and report the removal in the command's summary.

7. Guard-Rails

Inside any AKILI command:

  • Never offer Archify's explainer mode.
  • Never write an [archify explainer: …] line into any rules file.
  • Never install, update, snooze, or ignore Archify updates on your own initiative.
  • Relay an Archify update notice at most once per command run, as information only.
  • Use no third-party brand marks unless the user asks for them.
  • Never state an Archify command or flag in AKILI text; delegate them to Archify's own SKILL.md, and name only outcomes and locations.
  • Never alter the user's Archify configuration or environment variables.

8. Credit

Interactive views are rendered by Archify, by tt-a1i, MIT licence, https://github.com/tt-a1i/archify. It is referenced and never copied into the AKILI package; this skill ships no Archify file. Installing Archify is the user's choice and is documented in the project README, not performed here. The C4 model and Mermaid are credited in the frontmatter.

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.