skill-based-architecturelisted

# Skill-Based Architecture Restructure oversized single-file Skills or scattered project rules into a well-organized Skill directory. Builds on the official minimal Agent Skill contract (`name` + `description`) and kicks in when a single small `SKILL.md` is no longer enough. ## When to Use - A single SKILL.md exceeds ~150 lines, mixing rules, workflows, and background material - Project rules are scattered across `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `.cursor/rules/`, `.claude/`, `.codex/`, etc. - User explicitly requests Skill-based architecture or rule consolidation ## When NOT to Use - Very small projects (fewer than 3 rule/doc files) - Temporary repos with no long-term maintenance needs - Teams with a well-functioning documentation system who don't want to migrate ## Progressive Rigor Grow only under pressure. Tiers: **Single-file** (`SKILL.md` only, < 3 topics) → **Folder-light** (`+ rules/`, 3–5 topics or 1 recurring workflow) → **Full** (`+ workflows/` + `references/` + thin shells; ≥ 3 routed tasks, gotcha log, or multi-harness repo). Upgrade triggers: SKILL.md > 100 lines, same pitfall surfaces twice, a task needs step-by-step instructions, or two harnesses share routing. Downgrade when content shrinks. Details: [references/layout.md § Progressive Rigor](references/layout.md#progressive-rigor). ## Target Structure ```text skills/<name>/ ├── SKILL.md # ≤100 lines: always-read list, task routing, priority ├── rules/ # Long-lived constraints