AGENT SKILL

d2-diagrams

How a d2 diagram in this repo is drawn and rendered. Use when editing a `.d2` file, `docs/assets/diagrams/_palette.d2`, or `docs/assets/diagrams/render.sh`.

License 许可
MIT
所属仓库
muratovv/ai-hats
最近更新
2026-11-05
Stars
★ 3
Forks
1

01 前言 Front Matter

name
d2-diagrams
ai_hats
{ "type": "skill", "schema_version": 1 }
license
MIT
description
How a d2 diagram in this repo is drawn and rendered. Use when editing a `.d2` file, `docs/assets/diagrams/_palette.d2`, or `docs/assets/diagrams/render.sh`.

03 SKILL.md 正文

d2 diagrams

When to Use

Editing or adding a file under docs/assets/diagrams/. Not mermaid, and not the release checklist — that stays on the maintainer role.

Diagrams (d2)

Sources live at docs/assets/diagrams/*.d2; the brand-light palette is shared via docs/assets/diagrams/_palette.d2 (imported in every diagram as vars: @./_palette). Render with bash docs/assets/diagrams/render.sh [<stem>] — the script auto-extracts Source Code Pro Medium / SemiBold / Medium-Italic statics to $TMPDIR/ai-hats-fonts/ on first run. Commit both .d2 source and .svg artifact; do NOT commit .png. Full toolchain + shape conventions: CONTRIBUTING.md#diagrams.

Multiline labels. Inside default or double-quoted label strings, \n works for plain nodes:

node: First line\nSecond line
node2: "First line\nSecond line"

Single-quoted strings do NOT interpret escapes — 'foo\nbar' renders the literal \n characters. The |md ... | block syntax is reliable for shape: callout but fragile on plain nodes in sketch mode (labels often collapse to a single line) — prefer \n for plain nodes.

Theme overrides. vars.d2-config.theme-overrides applies to both light and dark theme-id standalone. The separate dark-theme-overrides field applies only when a light theme is the default and a dark theme is set as an alternate — using it for theme-id: 200 alone silently leaves the Catppuccin Mocha base in place on the first attempt.

Palette slot map (16 slots from _palette.d2): N1–N7 neutrals (text → cream background #faf2e6), B1–B6 navy spectrum (box fills, arrow strokes), AA2/AA4/AA5 brand-orange variants (AA4 = #e8632b, used for cylinder/oval storage shapes), AB4/AB5 cream/beige (soft accent parallelograms).

Containers + nested direction. direction: <inner> inside a container can be silently ignored by the ELK layout engine when it conflicts with the outer direction. The backlog FSMs were once attempted as one diagram with three containers → unreadable; resolved by splitting into 3 separate .d2 files. Prefer separate files for independent diagrams when more than ~10 nodes are involved.

Validation scenario

RED: asked to add a second line to a plain node, the agent writes 'foo\nbar'. The render shows the characters \n. The fix is a default or double-quoted label, where \n is a newline.

Completion

  • The diagram uses the shared palette and renders with render.sh.
  • A multiline plain-node label is not single-quoted.
  • Both the .d2 source and the .svg are committed. No .png.

Anti-Patterns

  • Single-quoted \n — the escape is drawn literally.
  • dark-theme-overrides on a standalone dark theme-id — the Mocha base stays.
  • One file of independent diagrams — ELK drops a nested direction.

04 同仓库更多 Skills

muratovv
muratovv/ai-hats

tool-evaluation-protocol

Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.

★ 3
muratovv
muratovv/ai-hats

systematic-debugging

4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.

★ 3
muratovv
muratovv/ai-hats

skill-template

Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

skill-optimization

Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.

Skill与智能体开发
★ 3
muratovv
muratovv/ai-hats

silent-fallback-gate

PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.

★ 3
muratovv
muratovv/ai-hats

retro-to-framework

Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.

Skill与智能体开发
★ 3