Skip to content

AGENTS.md

Latest commit

 

History

History
54 lines (39 loc) · 4.07 KB

AGENTS.md

File metadata and controls

54 lines (39 loc) · 4.07 KB
Raw

AGENTS.md — instructions for AI coding agents working in this repo

This repo is the source for the visualize agent skill. skills/visualize/ is the single authored and installable skill directory. Edit it directly; there are no distribution mirrors or placeholder transforms.

Editing workflow

  1. Edit runtime instructions and helpers under skills/visualize/; full catalog sources under catalog/; authoring tools under dev-scripts/. Run node dev-scripts/catalog-index.mjs after catalog edits to regenerate the bundled index and fallback.
  2. Run node dev-scripts/check-skill-package.mjs and the checks relevant to the change.

skills/visualize/design-systems/animation-patterns.md is runtime-owned shared guidance for animate and catalog preview authors. Edit it directly; catalog generation does not overwrite it.

Adding content

  • Template → skills/visualize/templates/<slug>/template.md. Keep the contract compact: frontmatter, use/exclusion rules, structure, creation guidance, hierarchy/mobile contracts, and concrete failure modes. See CONTRIBUTING.md for the canonical shape.
  • Design system → catalog/design-systems/<slug>/{DESIGN.md,tokens.css}.
  • Pattern recipe → skills/visualize/patterns/<slug>.md. Use for recurring creation guidance, not reusable component CSS.
  • Reference doc → skills/visualize/reference/<topic>.md. Lean intent + named failure modes only. Don't write defensive scaffolding.

Skill authoring split

  • Avoid duplication. Information should live in either SKILL.md or reference files, not both. Repeated rules drift, especially when a later edit fixes one copy and misses the other.
  • Keep SKILL.md procedural. SKILL.md should carry only essential procedural instructions, workflow guidance, command routing, shared contracts, and global rules. Move detailed reference material into focused files under skills/visualize/reference/.
  • Separate variations from the core workflow. When the skill supports multiple variations, keep only the shared workflow and selection guidance in SKILL.md. Move variant-specific details, examples, edge cases, and failure modes into separate reference files.
  • Reference docs defer to SKILL.md. Shared skill behavior belongs in SKILL.md. Reference docs should first apply the shared rules in SKILL.md, then describe only topic- or verb-specific procedure, failure modes, and consequences. Do not restate shared fallback logic, output shape, global bans, diff guards, or context-resolution policy in references.

Constraint discipline

Every constraint the skill imposes must answer: what bad output would result without this? "Consistency" or "the agent might choose differently" doesn't count. A constraint that can't name the failure mode it prevents is defensive; drop it. The skill's value comes from rules that catch real failure modes the agent reliably falls into.

Universal laws (override single rules)

  1. Brand and voice trump contextual taste rules; correctness constraints and explicit Absolute bans remain carve-outs.
  2. Verbs interpret, not regenerate.
  3. Ship-blockers and taste-calls are different.
  4. Severity follows context, including aggregate.
  5. Don't strip-mine into invisibility.
  6. The reader is the judge.

Repository layout

skills/visualize/              ← single authored and installed skill
├── SKILL.md
├── reference/                 ← typography / color / spatial / motion / copy
├── patterns/                  ← creation-time pattern recipes
├── design-systems/            ← generated index/source pin/Clean fallback + runtime-owned animation-patterns.md
├── templates/                 ← template contracts (template.md per template)
└── scripts/                   ← bash + Node helpers

catalog/design-systems/        ← full authoritative catalog and generated previews
dev-scripts/preview-kit/       ← development-only preview sources
skills/visualize/fixtures/     ← shared fixtures used by shipped check helpers
.github/workflows/ci.yml       ← standalone package + JSON lint + shellcheck