36 Specialists, One Prompt Away

An OrchestKit agent is a specialized AI persona built from four components:

Together these four pieces turn a general-purpose LLM into a focused specialist -- a security auditor that only reads code and never modifies it, a backend architect that designs APIs but never touches the frontend, or a debug investigator that forms hypotheses and traces execution paths.

What Is an Agent?

Every agent is defined in a single Markdown file at src/agents/<name>.md. The file has two parts:

1. YAML frontmatter -- structured metadata (model, tools, skills, hooks, category, color)
2. Markdown body -- the directive, task boundaries, output format, and integration notes

Here is a minimal example:

---
name: my-agent
description: What this agent does. Activates for keyword1, keyword2
model: sonnet
context: fork
tools:
  - Read
  - Write
  - Bash
skills:
  - relevant-skill-1
  - relevant-skill-2
---

## Directive
Clear instruction for what this agent does.

## Task Boundaries
**DO:** List what this agent should do
**DON'T:** List what other agents handle

How Agents Activate

Agents activate through two mechanisms:

1. Keyword Auto-Activation

Each agent's description field contains activation keywords. When your prompt matches those keywords, OrchestKit's hooks suggest the most relevant agent. For example:

• Typing "design a REST API for user management" matches backend-system-architect keywords: API design, REST, endpoint, route, authentication
• Typing "scan for security vulnerabilities" matches security-auditor keywords: security, vulnerability, CVE, audit, OWASP
• Typing "this component is broken, help me debug" matches debug-investigator keywords: bug, error, debug, crash, failure

2. Explicit Spawning

You can spawn any agent directly using the Task tool with a subagent_type parameter:

Task(
  description="Design the user API",
  subagent_type="backend-system-architect",
  prompt="Design RESTful endpoints for user management...",
  run_in_background=True
)

Workflow skills like /ork:implement and /ork:review-pr spawn multiple agents in parallel automatically.

Find Your Agent

Use the interactive selector to find the right specialist for your task.

Frontmatter Fields Explained

Model Assignment Strategy

The model field controls which LLM powers the agent:

• opus -- Used for complex reasoning tasks: architecture design, security auditing, system review, workflow design. 7 agents use Opus.
• sonnet -- Used for focused production tasks: demo video production. 1 agent uses Sonnet.
• inherit -- Uses whatever model the parent session is running. 28 agents inherit. This is the most flexible option and is recommended for most agents.

Context Isolation

The context field determines how the agent's context relates to the parent:

• fork -- The agent runs in an isolated context. It cannot see or modify the parent's state. This is the default for most agents and prevents unintended side effects.
• inherit -- The agent shares the parent's context. Used when the agent needs to see the current conversation state, such as the debug-investigator or code-quality-reviewer.

Agent Lifecycle

When an agent is spawned, it follows this lifecycle:

1. PROMPT           User types a request
                    |
2. KEYWORD MATCH    Hooks analyze prompt, suggest matching agent
                    |
3. AGENT SPAWNS     Claude Code creates a new task with:
                    - Model from frontmatter
                    - Tools from frontmatter
                    - Skills auto-injected from frontmatter
                    - Directive from markdown body
                    |
4. SKILL INJECTION  Skills listed in frontmatter are loaded
                    into the agent's context automatically
                    (CC 2.1.6+ auto-discovery)
                    |
5. HOOK EXECUTION   Agent-scoped hooks run (PreToolUse, PostToolUse)
                    Example: block-writes hook prevents read-only
                    agents from modifying code
                    |
6. EXECUTION        Agent performs its task using available tools
                    - Reads code, runs commands, analyzes patterns
                    - Follows its directive and task boundaries
                    |
7. RETURN           Agent produces structured output
                    - JSON report, review findings, or implementation
                    - Parent task receives the result

Agent-Scoped Hooks

Some agents define their own hooks in the frontmatter. These run only when that specific agent is active:

hooks:
  PreToolUse:
    - matcher: "Write|Edit"
      command: "${CLAUDE_PLUGIN_ROOT}/src/hooks/bin/run-hook.mjs agent/block-writes"

This pattern is used by read-only agents like security-auditor, debug-investigator, code-quality-reviewer, and system-design-reviewer to prevent them from modifying code. The deployment-manager uses a different hook (deployment-safety-check) to validate commands before execution.

The 36 Agents by Category

Backend (4 agents)

Frontend (4 agents)

Security (3 agents)

Testing (3 agents)

DevOps (5 agents)

LLM / AI (5 agents)

Product (5 agents)

Design & Research (5 agents)

Docs & Git (2 agents)

Skills Per Agent

Each agent carries a tailored set of skills. The backend-system-architect, for example, loads 31 skills covering API design, database schemas, caching, auth patterns, and more. The debug-investigator loads just 5 skills focused on root cause analysis and observability.

Skills are auto-injected when the agent spawns -- no manual loading required. The platform scales skill content to fit within 2% of the context window (CC 2.1.33+).

What's Next

• Choosing an Agent -- Decision tree for picking the right agent for your task
• Multi-Agent Patterns -- How /ork:implement and /ork:review-pr orchestrate agents in parallel
• Writing Agents -- Create your own specialized agent