Rules & skills
What an agent loads in an Aura project, when it loads it, and which file wins when two disagree.
How an agent reads an Aura project
.agents/ is the one home for agent files, whatever the tool. aura blueprint writes a managed block into the root AGENTS.md that tells every agent to apply .agents/rules/ and load skills from .agents/skills/, and a CLAUDE.md that imports it. Leftover .cursor/rules and .cursor/skills move into .agents/.
Three kinds of files steer an agent. A rule is a limit that always applies. A skill is a procedure the agent loads when the task matches its description. DESIGN.md is the narrative spec both point to.
| Layer | Path | Loaded | Holds |
|---|---|---|---|
| Always-on rules | .agents/rules/*.mdc | Every turn. The root AGENTS.md points every agent at it | Process policy: feature map, no comments, the DESIGN.md pointer, and Bruno on backends |
| Aura skill | .agents/skills/aura/ | When the task is UI | Design guardrails: color, type, 13px spacing, icons, motion, forms, lint |
| Procedure skills | .agents/skills/<name>/ | When the task matches the skill description | Steps: forms, UI verify, porting, feature map, brand images, DESIGN.md flavors |
| Narrative spec | DESIGN.md | When reasoning about tokens or brand | Theme, color roles, the grid, motion, product principles |
The full skill catalog, with triggers and install commands, is on Skills. Design guardrails are on Aura skill.
Which file wins
- The user's explicit instruction for the task.
- Always-on rules in
.agents/rules/. - The Aura skill and
DESIGN.md. - Upstream skills:
shadcn,gdp-ts. - Third-party audits. They return findings and never override Aura.
Install
| Project | Command | What it writes |
|---|---|---|
| Next.js or React app | pnpm dlx shadcn@latest add @aura/rules | feature-map, no-comments, design-md and root DESIGN.md |
| Any project, any language | npx @aura-design/cli@latest blueprint . | feature-map, no-comments, the feature map vault, and per stack Sonar, Bruno, and image generation. See CLI |
Install a single rule with pnpm dlx shadcn@latest add @aura/rule-<name>.
Rules in the registry
DESIGN.md (narrative spec)
Installs the agent rule into .agents/rules and the project root DESIGN.md (narrative spec). Add with shadcn as @aura/rule-design-md.
Feature map
The only project documentation is a feature map in the Obsidian vault, updated in the PR that changes a feature. No progress logs.
No code comments
Fix the root cause instead of commenting on it. Only external constraints, directives, licenses, and generated code carry comments.
Rules the CLI adds by stack
Bruno collection
Written by aura blueprint on backend projects. Each PR that changes an HTTP endpoint updates its .bru request in bruno/. Not in the registry.