Advanced Skills — Composition and Orchestration

When Single Skills Break

You built your first skills as single, self-contained instruction sets. That works well — until a skill grows complex enough that maintaining it becomes a problem in itself.

The signs a skill needs decomposition are recognizable:

• It runs for five minutes or more and involves multiple distinct phases
• Updating one part of the skill regularly breaks something else
• You cannot describe what the skill does in one sentence without using "and then"
• You want to reuse a piece of it in a different workflow but cannot extract it

The software engineering principle that fixes this is the same one that fixes it in code: single responsibility. Each skill should do one thing. An orchestrator skill coordinates the others. This is the composable sub-skill architecture.

The Composable Sub-Skill Architecture

The architecture has two types of skills:

Sub-skills each handle one specific task. They can be triggered directly by name, or they can be invoked by the orchestrator. They are small, focused, and independently testable. When you need to update the LinkedIn formatting logic, you edit only the LinkedIn sub-skill — nothing else breaks.

The orchestrator skill knows about all the sub-skills, decides when to call each, and assembles the final output. It is the coordinator, not the executor.

A practical example: start with a monolithic "Content Repurposer" skill that extracts a transcript, writes LinkedIn copy, formats an email, and posts a summary. Decomposed, this becomes:

• Content Extractor — reads source material and extracts key points
• LinkedIn Writer — formats extracted content for LinkedIn voice and length
• Email Formatter — formats the same content as a newsletter section
• Content Orchestrator — the parent skill that calls the above three in sequence

The prompt to generate this structure from an existing skill: "Split this skill into three sub-skills, with a parent skill that orchestrates all of them." Review the generated structure, refine the orchestrator's decision logic, then test each sub-skill independently before testing the full pipeline.

Orchestrator Skill Structure

A well-designed orchestrator skill has four sections:

1. Context — what this orchestrator manages and what its scope is
2. Available sub-skills — listed by name and their trigger phrase
3. Decision logic — when to call which sub-skill, in what order, and under what conditions
4. Output assembly — how to combine sub-skill outputs into the final deliverable

The decision logic section is what separates a real orchestrator from a skill that just mentions other skills. It must specify conditions: "If the input is a URL, call Content Extractor first. If the input is already text, skip extraction and go directly to LinkedIn Writer."

The API-Description Paradigm

Traditional skills are brittle because they describe steps. "Click the Export button, wait for the dialog, select CSV format, click Download." When the UI changes — and it will — the skill breaks.

The API-description paradigm inverts this. Instead of describing steps, you describe the service:

The Jira REST API is at https://your-domain.atlassian.net/rest/api/3/
Authentication: Basic auth with email + API token.
When I ask you to manage issues, use the appropriate Jira API
endpoints to accomplish the task. Documentation reference:
https://developer.atlassian.com/cloud/jira/platform/rest/v3/

Co-Work reasons about the API to accomplish the task. When the API adds a new endpoint or changes a parameter name, the skill adapts rather than breaking. The skill describes the contract; Co-Work figures out the implementation.

This approach works best for well-documented APIs with stable base URLs: Jira, GitHub, Notion, Linear, Salesforce, any service with a public REST API. It works less well for services where the documentation is poor or the API is frequently breaking.

Managing Skill Conflicts at Scale

As your skills library grows past 10 or 15 skills, a new problem emerges: Co-Work may activate the wrong skill. It reads through skill descriptions to determine which one matches your request — and when descriptions overlap, the wrong one fires.

Three strategies for conflict prevention:

1. Toggle off inactive skills. Skills you use less than once a week should be toggled off. They are still there when you need them; they just do not compete for every request.

2. Name orchestrators with unique, unambiguous triggers. "Run Content Pipeline" is unambiguous. "Content" is not. The trigger phrase should be specific enough that it cannot be confused with a sub-skill name. Jack Roberts recommends treating trigger words as reserved terms — do not use them in any other context in your instructions.

3. Add disambiguation notes to skill descriptions. If two skills handle similar content, add a line to each: "Use this ONLY for [specific context], NOT for [the other context]." These notes are instructions to Co-Work about when not to activate the skill.

The Weekly Orchestrator Review

Orchestrators are the most important skills to keep current. They coordinate everything, so when any sub-skill changes, the orchestrator may need an update. Jack Roberts recommends a weekly review cadence for the orchestrator layer — not for every skill, but for the orchestrators that coordinate them.

A five-minute weekly check: trigger each orchestrator with a test input. Does it call the right sub-skills? Does the output assembly still look correct? If a sub-skill changed this week, update the orchestrator's description of it. This prevents silent drift where the orchestrator's mental model of a sub-skill no longer matches what the sub-skill actually does.