Skill Composition

More Capability, Without a Bigger Skill

Skill Quality named the God Skill as an anti-pattern — one skill quietly trying to do three jobs at once. But real tasks genuinely do need multiple capabilities working together: a business intelligence request needs research, a database query, and a chart. The resolution isn’t to avoid ambitious tasks — it’s to build ambitious capability out of several narrow, well-scoped skills instead of one sprawling one. That’s composition.

Composition vs. God Skill: The Actual Difference

Both involve a task with several distinct parts. The difference is where the boundaries live.

God Skill: one SKILL.md, internally doing research, then a SQL query, then chart generation, with no clear seam between any of them. Editing the charting logic risks silently affecting the research instructions three sections up, because they’re the same file, loaded and reasoned about as one unit.

Composition: three separate skills — a research skill, a SQL skill, a visualization skill — each independently well-scoped, each independently testable, each following exactly one pattern from the design patterns lesson. The capability that results from using all three together is bigger than any one of them, but no individual file is doing more than one job.

The test that tells them apart: can each piece be tested, versioned, and reused on its own, separate from the others? If yes, it’s composition. If a piece only makes sense bundled with the rest, it was never actually separable — you may have just drawn the file boundaries in the wrong place.

Worked Example: A Business Intelligence Agent

Research Skill  +  SQL Skill  +  Visualization Skill
        │               │                │
        └───────────────┴────────────────┘
                         │
              Business Intelligence Agent

Research skill (a Planner pattern): given a business question, decides what data would answer it and where that data likely lives.

SQL skill (a Transformation pattern): given a specific, well-defined data need, writes and executes the query, returning structured results.

Visualization skill (also a Transformation pattern): given structured results, produces an appropriate chart — and, importantly, knows which chart type fits which kind of data, rather than defaulting to the same bar chart regardless of what was asked.

None of these three skills know about the other two. The research skill doesn’t need to know how SQL gets written; the SQL skill doesn’t need to know how the results will be charted. What connects them is the agent’s planning stage (from Where Skills Fit) — recognizing that a business intelligence question needs all three in sequence, activating each at the right moment.

Worked Example: Document Intelligence

OCR  +  Extraction  +  Validation  +  RAG
                    │
          Document Intelligence

OCR skill: converts a scanned document into raw text — a Transformation pattern, format A to format B.

Extraction skill: pulls structured fields out of that raw text — invoice number, date, line items — also Transformation, but a distinct one operating on different input.

Validation skill: checks the extracted fields against expected formats and business rules — a Validator pattern, exactly as covered two lessons back.

RAG skill: answers follow-up questions about the document’s content by retrieving relevant sections — its own distinct capability, not something OCR, extraction, or validation would naturally absorb.

A document arriving as a bad scan tests the OCR skill in isolation. A document that OCRs cleanly but has an unusual field layout tests extraction in isolation. Composition means each of those failure modes has exactly one place to look — which is the practical payoff, not just an organizational preference.

The Interface Each Skill Needs to Expose

Composition only works cleanly if each skill’s output is something the next skill (or the orchestrating agent) can actually consume. This is where the contract discipline from Skill Engineering matters most — a research skill whose output format varies unpredictably run to run makes the SQL skill’s job harder even though nothing about the SQL skill itself changed.

## Research skill — output contract

Always output:
1. The specific data question(s) identified
2. Which table(s) likely answer each question, if determinable
3. Any ambiguity that needs clarification before querying

Stating this contract explicitly is what lets the SQL skill (or the agent orchestrating both) rely on a consistent shape, rather than re-parsing free-form prose differently every time.

When Not to Compose

Composition adds real overhead — more skills to discover, more seams where something can go wrong, more to test independently. A task simple enough for one well-scoped skill doesn’t benefit from being artificially split into three. The signal that composition is warranted is the same signal that flags a God Skill in the first place: the task genuinely contains more than one kind of work, each following a different design pattern, each independently useful outside this specific combination.

Summary

• Composition solves the same problem a God Skill was trying to solve — ambitious, multi-part capability — but by combining several well-scoped skills instead of overloading one
• The test for whether something is composition or a mis-scoped God Skill: can each piece be tested, versioned, and reused independently?
• A business intelligence agent (research + SQL + visualization) and document intelligence (OCR + extraction + validation + RAG) are both compositions where each piece maps to exactly one design pattern
• Composition depends on each skill exposing a consistent output contract the next stage can actually consume — an unstated or inconsistent output shape undermines the whole benefit

Composing several skills for one agent is one level of scale. The next lesson goes one level further — distributing skill sets across multiple agents, each with a different job.