The 3 Building Blocks

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

103 skills covering: FastAPI, React, SQLAlchemy, RAG, LangGraph, OWASP, Terraform, and more.

Two Types

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:

---
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.

36 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:

Agent Anatomy

---
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:

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.

146 hooks across 11 categories:

Example: What Happens on a Git Push

When Claude runs git push, hooks fire in sequence:

Before execution (pretool):

After execution (posttool):

How They Connect

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

Next Steps

• Choosing a Plugin — Plugin installation options
• Installation — Get started in 2 minutes