---
title: "The 3 Building Blocks"
description: "Skills are knowledge, agents are specialists, hooks are automation. Here's how they work together."
canonical: "https://orchestkit.yonyon.ai/docs/foundations/skills-agents-hooks"
---

# The 3 Building Blocks

Skills are knowledge, agents are specialists, hooks are automation. Here's how they work together.

import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Count } from '@/components/count';

OrchestKit has three types of components. Understanding how they connect is the key to using the toolkit effectively.

## Skills — Reusable Knowledge

A skill is a markdown file containing expert knowledge about a specific topic. Think of skills as **reference cards** that Claude reads when it needs domain expertise.

```
src/skills/python-backend/SKILL.md
```

**<Count k="skills" /> skills** covering: FastAPI, React, SQLAlchemy, RAG, LangGraph, OWASP, Terraform, and more.

### Two Types

| Type | Count | How It Works | Example |
|---|---|---|---|
| **Command** | <Count k="commands" /> | You invoke directly: `/ork:commit` | `/ork:verify`, `/ork:implement` |
| **Reference** | <Count k="references" /> | Auto-injected into agents | `python-backend`, `security-patterns` |

Command skills are what you type. Reference skills are what agents read. You never need to invoke a reference skill — the right agent loads the right skills automatically.

### Skill Anatomy

Every skill has YAML frontmatter that controls how it's discovered and used:

```yaml
---
name: python-backend
description: Python backend patterns including FastAPI, async, middleware
tags: [python, fastapi, backend]
user-invocable: false     # Reference skill (not a command)
complexity: medium         # Helps Claude calibrate effort
agent: backend-system-architect  # Which agent uses this
---
```

## Agents — Specialized AI Personas

An agent is a **specialized Claude instance** with a specific role, tools, and injected skills. When you say "design a database schema", OrchestKit spawns the `database-engineer` agent — pre-loaded with schema design skills, migration patterns, and normalization knowledge.

**<Count k="agents" /> agents** covering: backend architecture, frontend UI, security auditing, test generation, debugging, deployment, and more.

### How Agents Activate

Agents activate from **keywords in your prompt**. You don't need to name them:

| You Say | Agent Spawned | Skills Loaded |
|---|---|---|
| "review this PR" | `code-quality-reviewer` | code-review-playbook, testing-unit, testing-e2e |
| "design the API" | `backend-system-architect` | api-design, architecture-patterns |
| "find the bug" | `debug-investigator` | errors, monitoring-observability |
| "optimize performance" | `frontend-performance-engineer` | performance, vite-advanced |
| "scan for vulnerabilities" | `security-auditor` | security-patterns, mcp-patterns |

### Agent Anatomy

```yaml
---
name: backend-system-architect
model: opus                    # Uses the most capable model
tools: [Read, Write, Bash, Grep, Glob]
skills:                        # 31 skills auto-injected
  - api-design
  - database-patterns
  - architecture-patterns
  # ...
---
```

### Parallel Agents

Some commands spawn **multiple agents in parallel**. When you run `/ork:review-pr`, three agents work simultaneously:

| Agent | Role |
|---|---|
| `security-auditor` | OWASP scan |
| `code-quality-reviewer` | Style and patterns |
| `test-generator` | Coverage gaps |

All three run in parallel, then results are synthesized into a single PR review.

## Hooks — Invisible Automation

Hooks are TypeScript functions that **fire automatically** on lifecycle events. You never invoke them — they run in the background on every prompt, tool call, and session transition.

**175 hooks** across 12 categories:

| Category | Count | What It Does |
|---|---|---|
| `pretool` | 24 | Runs before a tool executes (security gates, validation) |
| `posttool` | 19 | Runs after a tool executes (audit logging, metrics) |
| `prompt` | 14 | Runs when you submit a prompt (context injection, memory) |
| `lifecycle` | 16 | Session start/stop events (env setup, cleanup) |
| `skill` | 22 | Runs during skill execution (quality gates, patterns) |
| `agent` | 5 | Runs during agent operations (safety checks) |
| `permission` | 3 | Auto-approves safe operations |
| `stop` | 14 | Session end (save context, sync memory) |
| `subagent` | 11 | Manages sub-agent lifecycle |
| `setup` | 8 | First-run initialization |
| `notification` | 3 | Desktop/sound alerts |

### Example: What Happens on a Git Push

When Claude runs `git push`, hooks fire in sequence:

**Before execution (pretool):**

| Hook | Action |
|---|---|
| `dangerous-command-blocker` | Checks for force-push |
| `git-validator` | Validates branch rules |
| `compound-command-validator` | Checks piped commands |

**After execution (posttool):**

| Hook | Action |
|---|---|
| `audit-logger` | Records the action |
| `session-metrics` | Updates session stats |
| `workflow-analytics` | Updates workflow analytics |

## How They Connect

Here's what happens when you say **"Add user auth to the API"**:

<Steps>
  <Step>
    ### Prompt hooks fire
    `context-injector`, `memory-context-loader`, and `skill-auto-suggest` enrich your prompt with project context.
  </Step>
  <Step>
    ### Agent spawns
    **backend-system-architect** activates (model: opus) based on keyword matching.
  </Step>
  <Step>
    ### Skills injected
    The agent auto-loads `security-patterns`, `api-design`, `python-backend`, and `architecture-patterns`.
  </Step>
  <Step>
    ### Agent writes code
    Pretool hooks validate each tool call. Posttool hooks audit and log every action.
  </Step>
  <Step>
    ### Stop hooks
    `auto-remember-continuity` and `session-profile-agg` save context for the next session.
  </Step>
</Steps>

## Next Steps

- **[Choosing a Plugin](/docs/foundations/choosing-a-plugin)** — Plugin installation options
- **[Installation](/docs/getting-started/installation)** — Get started in 2 minutes