## Definition **Skill composition** is the practice of authoring skills that reference other skills — for example, a `cut-release` skill that invokes a `generate-changelog` skill as a step. The author of *Modern AI Software Engineering* establishes two governing rules: the dependency tree must stay at most two levels deep, and a flat folder of focused skills outperforms a clever hierarchy every time. ## The Two-Level Depth Limit When skill A calls skill B which calls skill C, the context window accumulates instructions from all three skills simultaneously (skills share the parent conversation's context — see [[Skill]]). Beyond two levels, the accumulated instructions become difficult for the model to track, the token cost grows materially, and debugging a failure requires tracing across multiple procedure documents. Two levels deep is a firm heuristic, not a soft preference. ``` cut-release (level 1 — the entry point) └─ generate-changelog (level 2 — direct dependency) └─ (stop here) (level 3 — forbidden) ``` ## Flat Folder Over Clever Hierarchy The temptation in a growing skill library is to introduce nested subdirectories — skills grouped by domain, phase, or team. The author's counter-principle: a flat folder of focused skills outperforms a clever hierarchy every time. The reasons are practical: - Discovery happens by description matching, not by browsing a tree. A flat folder with specific descriptions is found as easily as a deep hierarchy with vague ones. - Hierarchies encourage coarse-grained skills ("all release work lives in `release/`") rather than atomic ones. Atomic skills compose better and fail more cheaply. - Maintenance is cheaper when every skill is visible at a glance. A deep tree hides dead skills; a flat folder makes them obvious. ## When to Compose vs. When Not To Compose skills when a high-level procedure genuinely consists of two distinct, reusable sub-procedures — each of which is useful independently. Do not compose to avoid repetition: copy the two lines that overlap rather than add a dependency. | Compose | Do not compose | |---|---| | `cut-release` → `generate-changelog` (changelog useful standalone) | `deploy` → `check-lint` (lint check is one line; no standalone value) | | `onboard-teammate` → `seed-test-data` (seeding useful in other contexts) | `audit` → `cleanup` (cleanup is five words in the audit skill body) | ## Relationship to Context Window Budget Because skills load into the same context window, composing skills is not free. Each loaded skill consumes tokens. A two-level composition with long `SKILL.md` files can consume more context than a single flat procedure. When in doubt, prefer one longer skill over two composed short ones — the context cost of two files exceeds the cost of the combined prose. ## Related - [[Skill]] - [[Extension Trifecta]] - [[Context Window]] - [[AGENTS.md Convention File]] ## Sources - [[Modern AI Software Engineering - The Orchestrators Playbook]]