Knowledge base
Knowledge base: Claude Code, RAG and AI agents
Short articles on the building blocks of AI agents: subagents, hooks, skills and MCP in Claude Code, RAG and document search, multi-agent patterns and human approval. Each article comes with a whiteboard sketch, frequently asked questions and the public sources its facts come from.
Updated
Claude Code
How to split work between agents, stop an action before it runs, and give an agent tools and instructions.
Claude Code subagents: what they are and when to use them
A Claude Code subagent is a separate assistant with its own context window, its own system prompt and only the tools you allow it. Claude hands it a task, the subagent works on its own and sends back just a summary, so long logs and search results stay out of your main conversation.ReadClaude Code hooks: how to stop an action before it runs
A Claude Code hook is a handler that runs automatically at a fixed point in a session, such as a command, an HTTP call or a prompt. The PreToolUse hook runs before Claude uses a tool and can stop the call with exit code 2 or a deny decision, and the reason goes back to Claude.ReadClaude Code skills: instructions that load when needed
A Claude Code skill is a folder with a SKILL.md file that holds a name, a description and instructions. The description is always in context, so Claude knows which skills it has. The rest loads only when you run it with /name or when your request matches the description.ReadWhat is MCP (Model Context Protocol) and what an MCP server does
MCP (Model Context Protocol) is an open-source standard that connects AI applications to external systems such as files, databases, tools and services. An MCP server exposes tools, resources and prompts, and the application, for example Claude Code, opens one client for each server it connects to.Read
RAG and document search
How a model finds information in your documents and shows where it came from.
What is RAG in AI, and how does it work step by step?
RAG (Retrieval-Augmented Generation) means the model searches your documents first and writes the answer from what it found. The documents are split into chunks, each chunk becomes an embedding in an index, and for every question the chunks closest in meaning are added to the prompt next to the question.ReadHybrid search: BM25 and vector search in one query
Hybrid search runs the same query twice: once with BM25, which finds exact words and codes, and once against vectors, which find text that is close in meaning. The two result lists are merged, usually with Reciprocal Rank Fusion, and a reranker picks what finally reaches the model.ReadWhen not to use RAG
You do not need RAG when all your documents fit in the model's context window: put them straight into the prompt, and prompt caching makes repeated questions cheaper and faster. When they do not fit, an agent can search files itself as it goes. RAG with an index is the pick for large corpora when speed matters.ReadAI answers with citations: grounding an LLM in your sources
An answer with citations puts the passage that supports each claim right next to it. The model is allowed to say "I don't know", pulls the quotes first and answers second, and any claim without a quote is retracted. Hallucinations drop a lot but do not disappear, so a person checks the decisions that matter.Read
Agents and control
How several agents work together and where a person steps into the decision.
Orchestrator, workers and evaluator: patterns for AI agents
Orchestrator-workers is a pattern where a central model breaks a task down, hands the pieces to workers and combines their results. In evaluator-optimizer, one model generates and another evaluates, in a loop, until the result meets the criteria. Anthropic recommends the simplest solution that works, with more complexity only when needed.ReadHuman in the loop: when a person approves what an AI agent does
Human in the loop means a person approves an AI agent's high-impact actions before they happen. Everything else runs on its own with minimal tools and permissions, and authorization lives in the downstream systems, outside the model's judgment. That is how OWASP recommends keeping an agent with too much power in check.Read
What to use when in Claude Code
| Mechanism | What it is | When to use it |
|---|---|---|
| Subagent | A separate assistant with its own context, prompt and tools that returns only a summary. | When a task produces verbose output you don't need in the conversation, or needs restricted tools. |
| Hook | A handler that runs automatically at a session event, for example before a tool call. | When something must happen, or be blocked, regardless of what Claude decides. |
| Skill | A folder with a SKILL.md: the description is always in context, the instructions load when used. | For procedures you repeat and long instructions you only need some of the time. |
| MCP | An open standard that connects an AI application to external systems. | For data and actions in other systems when there is no command-line tool for them. |
| CLAUDE.md | Instructions read at the start of every session, treated as context rather than enforced configuration. | For what always holds: build commands, conventions, project layout. |