Core Principles

Progressive disclosure is the most critical principle. Load only what is needed, when it is needed.

• Level 1: Frontmatter — name + description. Always loaded. Under 1024 chars.
• Level 2: SKILL.md — core workflow. Loaded when triggered. Under 100 lines (under 500 is the hard limit).
• Level 3: References — deep docs. Loaded only when needed. Never nest deeper than one level.

Less is more. Target 60–120 lines for a project file, under 30 for global, under 80 for monorepo root. Imperatives over prose. Verifiable commands over descriptions. High-priority rules first. Security, irreversibility, and out-of-scope rules in the first 40 lines. IMPORTANT / YOU MUST sparingly. Reserve for the one or two truly critical rules. Negative rules matter. Without explicit "nevers," the agent picks the most common pattern. Don't duplicate the linter, the CI, or auto-memory. Delete anything tooling already enforces. No secrets. Ever. Not in SKILL.md, not in CLAUDE.md, not in CLAUDE.local.md.

See references/principles.md for full rationale.