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/, 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/progressive-rigor.md.