---
title: "Composing Skills Into Workflows"
description: "How command skills, reference skills, hooks, and agents combine to form intelligent workflows -- and when to use each composition pattern."
---

## The Composition Model

OrchestKit does not have a single orchestration engine. Instead, skill composition emerges from three independent mechanisms working together:

1. **Hook-based injection** -- The `skill-auto-suggest` hook matches keywords in your prompt and injects relevant skills into context.
2. **Command skill composition** -- A command skill's `skills:` frontmatter field loads reference skills alongside the workflow.
3. **Agent skill injection** -- An agent's `skills:` frontmatter field ensures it always has domain-specific knowledge.

These mechanisms stack. A single interaction can involve all three, producing a rich context that combines workflow instructions, domain knowledge, and project-specific patterns.

---

## Anatomy of a Composed Workflow

Here is what happens when you type `/ork:implement payment processing`:

```
Step 1: You invoke /ork:implement
        -> Command skill "implement" loads

Step 2: implement's frontmatter pulls in reference skills:
        -> api-design-framework
        -> react-server-components-framework
        -> type-safety-validation
        -> unit-testing
        -> integration-testing
        -> explore
        -> verify
        -> memory
        -> worktree-coordination

Step 3: implement asks you for scope (full-stack, backend, etc.)

Step 4: implement spawns parallel agents:
        -> backend-system-architect (gets its own skills:
           fastapi-advanced, sqlalchemy-2-async, etc.)
        -> frontend-ui-developer (gets its own skills:
           shadcn-patterns, zustand-patterns, etc.)
        -> test-generator (gets its own skills:
           pytest-advanced, integration-testing, etc.)

Step 5: Each agent works with full knowledge from
        both the command's skills AND its own skills

Step 6: implement's verify step runs /ork:verify,
        which spawns its own parallel test agents
```

The total knowledge context for this interaction might include 15-20 skills, all loaded transparently without you specifying any of them.

---

## Composition Patterns

### Pattern 1: Direct Command

The simplest pattern. You invoke a command skill, and it handles everything.

```
/ork:commit
```

The `commit` skill runs in `inherit` context (it needs to see your staged changes), loads `git-recovery` as a companion skill, and produces a conventional commit message. No agents spawn. No additional skills are suggested.

**When to use:** For focused, single-purpose tasks where the command skill contains all needed knowledge.

### Pattern 2: Command + Parallel Agents

The most powerful pattern. A command skill spawns multiple agents that work in parallel, each with their own skill sets.

```
/ork:implement search feature
```

The `implement` skill forks context, loads 9 reference skills, asks for scope, then spawns 2-4 agents depending on your answer. Each agent receives its own reference skills from its frontmatter.

**When to use:** For multi-step feature development, complex investigations, or comprehensive reviews.

### Pattern 3: Hook Auto-Suggestion

No command invoked. You type a regular prompt, and the skill-auto-suggest hook detects relevant keywords.

```
How should I structure the database schema for user permissions?
```

The hook detects "database" and "schema", injects `database-schema-designer` (confidence 80) and potentially `auth-patterns` (confidence 60) into the response context. Claude then uses those patterns to answer.

**When to use:** For questions and exploratory conversations. You do not need to remember which skills exist -- the hook handles discovery.

### Pattern 4: Agent Cascade

An agent spawned by one command invokes behavior that triggers additional skill injection.

```
/ork:fix-issue 456
```

The `fix-issue` command spawns a `debug-investigator` agent. That agent has `root-cause-analysis` in its skills. During investigation, it might spawn a sub-agent `test-generator` that brings `pytest-advanced` and `integration-testing`. The skill set grows organically as agents delegate work.

**When to use:** For complex debugging or investigation where the needed skills are not known upfront.

---

## /ork:implement vs. Manual Prompting

A common question: when should you use `/ork:implement` versus just describing what you want in a regular prompt?

| Factor | `/ork:implement` | Manual prompt |
|--------|-------------------|---------------|
| **Structure** | Multi-phase workflow with scope clarification, parallel agents, and verification | Single-shot response |
| **Skills loaded** | 9+ reference skills plus agent-specific skills | 0-3 skills via hook auto-suggest |
| **Agent count** | 2-4 parallel agents | 0 (main conversation only) |
| **Verification** | Built-in `/ork:verify` step | Manual, if you remember |
| **Token cost** | Higher (parallel agents, more context) | Lower |
| **Best for** | Features requiring multiple files, tests, and coordination | Small changes, single-file edits, questions |

**Rule of thumb:** If the task touches 3+ files or needs both implementation and tests, use `/ork:implement`. If it is a single-file change or a question, a regular prompt with hook auto-suggest is sufficient.

---

## Cost and Context Tradeoffs

Skills consume context window budget. More skills means richer knowledge but less room for code and conversation. Here are the tradeoffs:

### Context Budget

Claude Code 2.1.33+ allocates approximately 2% of the context window for skill content. With a 200K context window, that is roughly 1,200 tokens for skills. With 1M context, roughly 6,000 tokens.

When multiple skills are injected, the platform prioritizes by relevance score. Lower-priority skills may be truncated or omitted if the budget is exhausted.

### Token Cost Per Pattern

| Pattern | Approximate extra tokens | When it pays off |
|---------|--------------------------|-------------------|
| Hook auto-suggest (1-3 skills) | 500-1,500 | Always -- nearly free, prevents common mistakes |
| Command skill + references | 2,000-4,000 | Multi-step tasks where the workflow prevents rework |
| Command + parallel agents | 10,000-30,000 | Complex features where parallel work saves wall-clock time |

### When Composition Gets Expensive

The highest cost scenario is `/ork:implement` with full-stack scope on a large codebase. It spawns multiple agents, each loading multiple skills, each reading many source files. For a typical feature implementation, expect 50,000-100,000 tokens total across all agents.

This is almost always worthwhile for real features, because the alternative -- implementing without tests, missing security patterns, or forgetting to validate types -- costs more in debugging and rework.

---

## Skill Interaction Patterns

### Skills That Reinforce Each Other

Some skill combinations produce better results than either alone:

- `api-design-framework` + `fastapi-advanced` -- General API principles applied through FastAPI-specific patterns.
- `database-schema-designer` + `alembic-migrations` -- Schema design with migration-aware constraints.
- `owasp-top-10` + `input-validation` -- Vulnerability awareness paired with concrete prevention code.
- `unit-testing` + `pytest-advanced` -- Test philosophy combined with framework-specific techniques.

### Skills That Set Boundaries

Some skills constrain each other constructively:

- `clean-architecture` + `backend-architecture-enforcer` -- Design principles paired with automated enforcement.
- `type-safety-validation` + `integration-testing` -- Static guarantees complemented by runtime verification.
- `quality-gates` + `test-standards-enforcer` -- Quality thresholds applied to test coverage and conventions.

---

## Debugging Composition Issues

### "Claude did not use the pattern from skill X"

Check whether the skill was actually injected:

1. Run `/ork:doctor` to verify the skill exists and is loadable.
2. Check if the skill's keywords match your prompt (for hook auto-suggest).
3. Check if the agent you are using lists the skill in its frontmatter.
4. Check if the context budget was exhausted -- if many skills competed, lower-priority ones may have been truncated.

### "Too many skills are being suggested"

The `skill-auto-suggest` hook has a minimum confidence threshold of 30 and a maximum of 3 suggestions. If irrelevant skills appear, the issue is usually broad keywords. For example, "test" matches `integration-testing` at confidence 60 even if you meant "test the deployment".

The hook cannot be tuned per-session today. If auto-suggestions are consistently unhelpful for your domain, the best workaround is to use command skills (which load their own explicit skill sets) rather than relying on auto-suggest.

---

## What's Next

- [23 Command Skills](/docs/skills/command-skills) -- See the full list of commands and what they compose.
- [61 Reference Skills](/docs/skills/reference-skills) -- Browse the knowledge library by domain.
- [Create Your Own SKILL.md](/docs/skills/writing-skills) -- Add skills tailored to your project.
