Orchestrating AI Agent Teams: How Skills, Hooks, and Context Flow Make Autonomous Coding Reliable#

What Is Claude Code?#

Claude Code is an AI coding agent that runs in your terminal. It reads files, writes code, runs shell commands, and searches codebases. Every action the agent takes is called a tool call: writing a file is a tool call to Write, running a test suite is a tool call to Bash, reading a file is a tool call to Read.

Think of it like a developer who works entirely through a command line. The developer has a set of tools (editor, terminal, file browser) and uses them in sequence to accomplish tasks. Claude Code works the same way but with an LLM making the decisions about which tool to use next.

The critical limitation: the LLM has a context window, a fixed amount of working memory. When the context window fills up, older information gets compressed or lost. This is why purely prompt-based instructions are unreliable for long sessions. The agent might forget instructions it read 30 minutes ago.

What Are Skills?#

A skill is a markdown file (SKILL.md) that gives an agent specialized knowledge for a specific type of task. Think of it as a runbook or playbook that gets loaded into the agent’s context when relevant.

Figure 2 - Skills as Agent Knowledge: A skill is a markdown file with a name, description, and instructions. The description loads at session start so the agent knows the skill exists. The full instructions load only when the agent needs them. Supporting files (reference docs, scripts, examples) load on demand, keeping the context window efficient.

A skill has two parts:

1. YAML frontmatter: metadata including the skill’s name and description. The description loads at session start so the agent knows the skill exists.
2. Markdown body: the actual instructions, patterns, templates, or workflows. This loads only when the skill is invoked.

1
---
2
name: api-conventions
3
description: API design patterns for this codebase. Use when writing
4
  or reviewing API endpoints.
5
---
6

7
When writing API endpoints:
8
- Use RESTful naming conventions
9
- Return consistent error formats with status codes
10
- Include request validation on all inputs
11
- Log all requests with correlation IDs

The CS analogy: Skills are like library documentation. You do not read the entire docs for every import. You read the relevant section when you need it. Skills work the same way: descriptions are always visible (like a library index), full content loads on demand (like opening a specific page).

Skills can also bundle supporting files (reference docs, scripts, examples) in a directory structure. The main SKILL.md acts as a table of contents, pointing the agent to detailed resources only when needed. This is called progressive disclosure and it keeps the context window efficient.

What Are Slash Commands?#

A slash command is how you invoke a skill directly. Every skill with a name automatically becomes a /name command. Type /deploy in the terminal and the deploy skill activates. Type /fix-issue 123 and the fix-issue skill activates with 123 as its argument.

Figure 3 - Slash Commands: Bridging Users, Agents, and Skills: Slash commands turn skills into invocable actions. The user types /fix-issue 123, the skill activates with the argument, and instructions flow into the agent. Skills can run inline (in the main context) or fork into an isolated subagent. Invocation control determines who can trigger a skill: only the user, only the agent, or both.

Slash commands are more than just a shortcut. They are the primary mechanism for creating repeatable, parameterized workflows that both humans and agents can trigger. Here is what makes them powerful:

Arguments with $ARGUMENTS: Skills accept arguments that get substituted into the instructions. The skill body references $ARGUMENTS (all arguments) or $0, $1, $2 for positional access.

1
---
2
name: fix-issue
3
description: Fix a GitHub issue by number
4
disable-model-invocation: true
5
---
6

7
Fix GitHub issue $ARGUMENTS following our coding standards.
8
1. Read the issue description
9
2. Implement the fix
10
3. Write tests
11
4. Create a commit

Running /fix-issue 123 replaces $ARGUMENTS with 123. The agent receives concrete, actionable instructions with the specific issue number baked in.

**Dynamic context with !command**: Skills can inject live data from shell commands before the agent sees anything. The `!`command syntax runs the command and replaces the placeholder with its output.

1
---
2
name: pr-summary
3
description: Summarize changes in a pull request
4
context: fork
5
agent: Explore
6
---
7

8
## Pull request context
9
- PR diff: !`gh pr diff`
10
- PR comments: !`gh pr view --comments`
11
- Changed files: !`gh pr diff --name-only`
12

13
Summarize this pull request.

When /pr-summary runs, the gh commands execute first. The agent receives the actual diff, comments, and file list, not the commands themselves. This is preprocessing, not agent execution.

Forking into subagents with context: fork: A skill can run in the main conversation context (default) or fork into an isolated subagent. Forking is useful for tasks that produce verbose output (like running a full test suite) or tasks that should not pollute the main context window. The agent field specifies which subagent type to use.

Invocation control: Two frontmatter fields control who can trigger a skill:

• disable-model-invocation: true: Only the user can invoke it. Use for workflows with side effects like /deploy or /send-slack-message. You do not want the agent deciding to deploy because the code looks ready.
• user-invocable: false: Only the agent can invoke it. Use for background knowledge that is not actionable as a command.

How the orchestrator uses slash commands: In an agent team, the orchestrator can invoke skills programmatically via the Skill tool. When the orchestrator encounters a task that matches a skill’s description, it triggers the skill to inject that domain knowledge into its workflow. Specialized agents can also have skills preloaded at spawn, making slash commands available from the agent’s first action. This means the entire team can leverage a shared library of repeatable workflows: the orchestrator triggers /review-pr to spawn a review, the builder triggers /run-tests after implementation, and the validator invokes /check-coverage during its inspection.

The CS analogy: Slash commands are like CLI commands in a Unix system. ls, grep, and make are standard tools available to every user. Slash commands are standard workflows available to every agent. Just as you can pipe commands together (git diff | grep TODO), agents can chain slash commands in sequence. And just as Unix permissions control who can run sudo, invocation control determines who can trigger each slash command.

What Are Hooks?#

A hook is a shell command that fires automatically at a specific point in the agent’s lifecycle. Hooks are not prompts. They are not suggestions. They are system-level interceptors that execute outside the LLM’s reasoning chain.

Figure 4 - Prompts Suggest, Hooks Guarantee: A prompt in CLAUDE.md achieves roughly 80% compliance. The agent usually follows it but can skip under context pressure. A PostToolUse hook achieves 100% compliance. It runs at the system level, every time, regardless of what the agent is thinking.

There are two critical hook events for understanding context flow:

• PreToolUse: fires before every tool call. Can allow, deny, or escalate the action. This is your safety gate.
• PostToolUse: fires after every tool call. Can inject additionalContext back into the agent. This is your quality gate.

The CS analogy: Hooks are middleware. In an Express.js web server, middleware intercepts HTTP requests before they reach your route handler. Hooks intercept the agent’s tool calls before and after they execute. PreToolUse is like authentication middleware (block unauthorized requests). PostToolUse is like response middleware (transform or validate output).

What Is an Orchestrator?#

An orchestrator is a lead agent that coordinates work across a team of specialized agents. It does not write code itself. It breaks tasks into work items, assigns them to specialists, monitors progress, and synthesizes results.

Figure 5 - The Orchestrator Pattern: The orchestrator coordinates without implementing. It maintains a shared task list, assigns work to specialized agents, and synthesizes results. Each agent operates in its own context window with its own tools, skills, and hooks. The task list is the shared coordination mechanism.

The CS analogy: The orchestrator is like a project manager running a sprint. The project manager does not write code. They break stories into tasks, assign them to developers, review progress, and handle blockers. The shared task list is the sprint board. Each developer (agent) picks up tasks and reports back.

Phase 1: Session Start#

When a session begins, the SessionStart hook fires. This is your opportunity to inject the project’s current state into every agent’s awareness before any work begins.

Figure 6 - Session Start Context Loading: The SessionStart hook gathers project state (git info, context files, issues, environment) and injects it as additionalContext. The agent starts with full project awareness instead of spending tokens discovering its environment.

A typical session_start.py hook:

1. Reads the current git branch and uncommitted change count
2. Loads project context files (TODO.md, CONTEXT.md)
3. Fetches recent GitHub issues via the gh CLI
4. Packages everything into additionalContext and returns it as JSON

1
# From session_start.py -- context loading
2
context_parts = []
3
context_parts.append(f"Git branch: {branch}")
4
context_parts.append(f"Uncommitted changes: {changes} files")
5

6
for file_path in [".claude/CONTEXT.md", "TODO.md"]:
7
    if Path(file_path).exists():
8
        content = open(file_path).read().strip()
9
        context_parts.append(f"--- Content from {file_path} ---")
10
        context_parts.append(content[:1000])
11

12
output = {
13
    "hookSpecificOutput": {
14
        "hookEventName": "SessionStart",
15
        "additionalContext": "\n".join(context_parts)
16
    }
17
}
18
print(json.dumps(output))

The Setup hook goes further. It runs when the agent first enters a repository and can persist environment variables across sessions using CLAUDE_ENV_FILE. It distinguishes between init mode (first entry, install dependencies, set up environment) and maintenance mode (periodic checks, disk usage, git status).

The CS analogy: SessionStart is like the constructor of a class. Before any methods run, the constructor initializes state. The hook initializes the agent’s awareness of the project before any tool calls happen.

Phase 2: Skill Loading#

Once the session is running, skills determine what the agent knows. Skills can be loaded two ways:

1. On demand: The agent encounters a task that matches a skill’s description and loads it.
2. Preloaded: The skill content is injected into the agent’s context at startup (used for subagents).

Figure 7 - Two Skill Loading Modes: In the main session, only skill descriptions are in context. Full content loads on demand when relevant. For subagents, skills are preloaded at startup, injecting the full content into the agent’s context immediately. This gives specialized agents complete domain knowledge from their first action.

When skills are preloaded into a subagent, the agent definition specifies which skills to load:

1
---
2
name: api-developer
3
description: Implement API endpoints following team conventions
4
skills:
5
  - api-conventions
6
  - error-handling-patterns
7
---
8

9
Implement API endpoints. Follow the conventions and patterns
10
from the preloaded skills.

The CS analogy: On-demand skill loading is like lazy evaluation in functional programming. You do not compute a value until you need it. Preloaded skills are like eager evaluation. You compute everything upfront because you know the subagent will need it.

Phase 3: The Tool Call Loop#

Every action the agent takes passes through two hook gates: PreToolUse (before) and PostToolUse (after). This loop runs hundreds of times per session. It is the heartbeat of the system.

Figure 8 - The Tool Call Loop: Every tool call passes through PreToolUse (safety gate) and PostToolUse (quality gate). The PostToolUse hook runs validators and injects errors back as additionalContext. The agent reads the feedback and self-corrects in its next action. This loop runs hundreds of times per session with zero human intervention.

Here is the critical mechanism: additionalContext.

When a PostToolUse hook finishes running, it can return a JSON object with an additionalContext field. Claude Code takes that string and injects it directly into the agent’s conversation context. The agent sees this feedback as if someone told it something important, and it acts on it.

1
# PostToolUse hook: Run TypeScript compiler after file writes
2
result = subprocess.run(
3
    ["npx", "tsc", "--noEmit", "--pretty"],
4
    capture_output=True, text=True, timeout=30
5
)
6

7
if result.returncode != 0:
8
    error_lines = [l for l in result.stdout.split("\n") if ": error TS" in l]
9
    output = {
10
        "additionalContext": (
11
            f"TypeScript errors detected: {len(error_lines)} error(s). "
12
            f"Fix these before continuing to the next task."
13
        )
14
    }
15
    print(json.dumps(output))

The CS analogy: additionalContext is like a CI/CD pipeline posting comments on a pull request. You push code, the pipeline runs checks, and posts a comment with specific errors. You read the comment and fix the issues. The hook is that pipeline, and additionalContext is that comment, except it happens inside the agent’s mind, instantly, on every single file write.

Phase 4: Per-Agent Hooks#

In a team of agents, a global hook that validates CSV structure on every file write would be wasteful for the API developer. Conversely, the API developer needs OpenAPI spec validation that would be irrelevant for the CSV analyst. Per-agent hooks solve this.

Figure 9 - Per-Agent Specialization: Global hooks waste computation by running irrelevant validators on every agent. Per-agent hooks embedded in agent definitions apply only the validation each specialist needs. The builder runs linters after every write. The validator enforces read-only access. Each agent’s hooks are part of its identity.

Hooks are embedded directly in the agent definition file:

1
---
2
name: builder
3
description: Focused engineering agent that executes ONE task at a time.
4
model: opus
5
color: cyan
6
hooks:
7
  PostToolUse:
8
    - matcher: "Write|Edit"
9
      hooks:
10
        - type: command
11
          command: "uv run .claude/hooks/validators/ruff_validator.py"
12
        - type: command
13
          command: "uv run .claude/hooks/validators/ty_validator.py"
14
---
15

16
You are a focused engineering agent. You build, implement, and create.
17
You do not plan or coordinate. You execute.

The builder agent carries PostToolUse hooks that run ruff (Python linter) and ty (type checker) after every Write or Edit. The validator agent uses disallowedTools: Write, Edit to enforce read-only access deterministically, not by instruction but by capability restriction.

The CS analogy: Per-agent hooks are like microservice-specific middleware. Each microservice in your system has its own middleware stack. The payment service has fraud detection middleware. The auth service has rate limiting middleware. You do not run fraud detection on the auth service. Same principle.

Phase 5: The Complete Context Flow#

Now let us trace context through an entire task, from the user’s request to task completion.

Figure 10 - The Complete Context Journey: Context flows from user request through orchestrator planning, agent spawning (with skill injection and session context), the hook-enforced tool call loop (with additionalContext feedback), task completion, validation review, and finally synthesis back to the user. Every stage adds or validates context deterministically.

Here is the flow:

1. User request arrives: “Add error handling to the API endpoints.”
2. Orchestrator breaks it into tasks on the shared task list.
3. Builder agent spawns with preloaded skills (api-conventions, error-handling). SessionStart hook injects git state and project context.
4. Builder works. Every file write triggers PostToolUse hooks (ruff, ty). Errors flow back as additionalContext. Builder self-corrects.
5. Builder completes. Marks task done with a summary of what changed.
6. Validator agent spawns with read-only tools. Reviews the changed files. Runs tests. Reports pass/fail.
7. Orchestrator synthesizes results across all tasks. Reports to user.

At every stage, context enters the system through a deterministic mechanism: SessionStart hooks, preloaded skills, additionalContext from PostToolUse hooks, task summaries from completed agents. Nothing depends on the agent remembering an instruction from 30 minutes ago.