Revision control
Copy as Markdown
# The Seven Skill-Loading Patterns
Canonical reference for how agents in the Qt Doc Agent Framework load
skills. Every agent's definition names which patterns it uses; the
orchestrator picks patterns 6 (hierarchical) and 7 (verification) at the
framework level.
Adapted from established Claude Code skill-design practice; the summary
table and detailed sections below are the framework's public reference.
## Summary
| # | Pattern | How it works | Best for | Watch out for |
|---|---------|--------------|----------|---------------|
| 1 | **System Prompt Embedding** | Rules pasted into the system prompt | Small, stable rule sets needed every run | Uses up context permanently; doesn't scale past ~2 skills |
| 2 | **Upfront Loading** | Agent reads all skill files at start | Short workflows; skills needed continuously | Claude forgets earlier content in long conversations; wastes memory on irrelevant skills |
| 3 | **GATE-Based / Just-in-Time** | Agent reads a specific skill at each decision point | Multi-step workflows; large skill libraries | More complex prompt design; extra file reads per run |
| 4 | **RAG / Retrieval** | External search retrieves relevant passages | Very large knowledge bases (100+ docs) | Rules may get cut in half during retrieval; less control over what's retrieved |
| 5 | **Tool-Based Lookup** | Skills exposed as tools the agent calls on demand | Exploratory tasks; strong models (Opus) | Agent may skip lookups; hard to verify which rules were checked |
| 6 | **Hierarchical / Cascading** | Knowledge split across prompt layers (orchestrator → agent → skill) | Multi-agent systems with an orchestrator | Adds complexity for single-agent setups |
| 7 | **Multi-Agent Verification** | Second pass checks first agent's output against the rules | High-stakes outputs where errors are costly | Slower; doubles compute; needs concrete verification criteria |
**The framework's stack combines 1 + 2 + 3 + 6 + 7.** Most real agents
layer multiple patterns.
## How to pick a pattern
Decision tree (in order — take the first `YES`):
- Small, stable, always-needed rule set? → **Pattern 1: System Prompt Embedding.**
- Skill needed at one specific step in a multi-step workflow? → **Pattern 3: GATE-Based** (the recommended default).
- Skill needed continuously across a short workflow? → **Pattern 2: Upfront Loading.**
- Knowledge base too large to fit in any prompt? → **Pattern 4: RAG.**
- Skill better modeled as a tool call the agent decides when to invoke? → **Pattern 5: Tool-Based Lookup.**
- Multi-agent system with an orchestrator? → **Pattern 6: Hierarchical** (combine with Pattern 3).
- High-stakes output where errors are costly? → **Add Pattern 7: Multi-Agent Verification.**
## How the framework uses each pattern
| # | Where |
|---|-------|
| 1 | Orchestration rules embedded in [`../CLAUDE.md`](../CLAUDE.md). |
| 2 | Initial-check pair (`skill-framework-fitness` + `skill-security-hygiene`) loaded upfront on every dispatch. |
| 3 | Stage agents GATE-load skills at the decision point they apply to. Recommended default for new agents. |
| 5 | Tool wrappers live in [`../tools/`](../tools/); a skill invokes them at a specific step. No tool shipped yet. |
| 6 | The four-layer chain (**harness → orchestrator → agent → skill**) is Pattern 6 by construction. |
| 7 | Orchestrator's post-agent verification gates (see [`../agents/orchestrator.md`](../agents/orchestrator.md)). |
Pattern 4 (RAG) is not used and is not planned; the framework's
knowledge base is small enough that GATE-based loading handles it
without retrieval overhead.
## Pattern 1: System Prompt Embedding
**How it works.** Rules are pasted directly into the system prompt so
the model always has them in context.
**Tradeoffs.** Maximum recall — the model never forgets what's in its
prompt. But it permanently uses up context window space on every run,
whether or not the rules are relevant. Doesn't scale past roughly two
skills' worth of content before it crowds out the memory Claude needs
for the actual task.
**Example in this framework.** `../CLAUDE.md` embeds harness orientation
directly: the layer hierarchy, the environment, the resource-priority
rule. Every framework session sees this content because the harness
loads CLAUDE.md automatically.
**When to use it:**
- Small, stable rule sets (under ~2,000 tokens, roughly 1,500 words).
- Rules needed on every run (routing, environment, output-format skeleton).
- Configuration that rarely changes.
**When to avoid it:**
- Large or growing knowledge bases.
- Rules that only apply to specific task types.
- Content that changes frequently (each edit means updating the prompt).
## Pattern 2: Upfront Loading
**How it works.** The agent reads all its skill files at the start of
a run, before doing any work.
**Tradeoffs.** Simple to implement — just list the files to read in the
agent prompt. But it wastes memory on skills that may not be relevant,
and the content goes stale: by the time the agent reaches Step 8 and
needs formatting rules it read at Step 1, that content is far back in
the conversation and Claude pays less attention to it.
**Example in this framework.** The orchestrator's pre-flight loads the
initial-check pair upfront on every dispatch:
```
Load before routing to the stage agent:
- skills/skill-framework-fitness/SKILL.md
- skills/skill-security-hygiene/SKILL.md
```
These two skills apply to *every* framework artifact regardless of
pipeline, so paying the upfront cost is worth it — a GATE at every
possible decision point would be wasteful. Every other framework skill
is a candidate for Pattern 3 instead.
**When to use it:**
- Skills needed continuously throughout a short workflow.
- Small skill files (under ~1,000 tokens each).
- When context decay isn't an issue (workflows under ~10 steps).
**When to avoid it:**
- Long multi-step workflows (10+ steps) — content decays; use Pattern 3.
- Large skill files — pay the cost only at the step that needs them.
- When only a subset of rules applies to any given task.
**Failure mode this addresses.** An early version of a hypothetical
review agent could load ten skills at Step 1 (~4,000 lines total). By
Step 8, when it needs the output-format template, that template is
thousands of lines back in the conversation. The agent produces
plain-text output instead of Doc Team diff format — it has "forgotten"
the template it read at the start. Fix: switch that template to
Pattern 3 and load it at Step 8, right when the agent needs it.
## Pattern 3: GATE-Based / Just-in-Time Loading
**This is the recommended default for framework agents.** Handles the
widest range of workflows.
**How it works.** The agent workflow defines explicit decision points
(GATEs) where the agent must stop, read a specific skill file, apply
it, and show evidence it followed the skill before continuing.
**Tradeoffs.** Efficient context use — only the relevant skill is in
working memory when it's applied. Fresh recall at the decision point.
Auditable, because the agent must cite evidence. But it requires more
complex prompt engineering: you design the workflow with explicit gates
and specify which skill maps to which step.
**Example shape for a new agent.** An agent definition that uses
Pattern 3 looks like this:
```markdown
## Design principle: skills at decision points
Do NOT load all skills upfront. Load the specific skill at the moment
you need it to make a decision. This keeps the skill fresh in context
when applied and forces you to follow the skill as a procedure rather
than from memory.
### Step 4: Diagnose
**GATE — Read the skill matching the input type before proceeding.**
| Input type | Read this now |
|------------------|--------------------------------------------|
| {type A} | ../skills/skill-{name-a}/SKILL.md |
| {type B} | ../skills/skill-{name-b}/SKILL.md |
### Step 8: Format output
**GATE — Read ../skills/skill-doc-diff/SKILL.md NOW.**
```
Every GATE requires evidence: the agent produces a "Skills Loaded"
block, a validation output, a grep result, or a citation showing it
followed the skill.
**How to design a GATE-based agent:**
1. Map the workflow as numbered steps.
2. Identify which steps require reference material.
3. For each step, name the exact skill file and section.
4. Label those steps GATE.
5. Require evidence (validation output, grep results, citations) that
the skill was followed.
**When to use it:**
- Multi-step workflows with distinct decision points.
- Large skill libraries where only two or three skills apply per task.
- When auditability matters — you need to prove rules were followed.
- Skills that change often; fresh reads pick up revisions.
**When to avoid it:**
- Simple single-step tasks.
- When the same skill is needed continuously (Pattern 2 is simpler).
- When Read-call overhead is a real concern.
## Pattern 4: RAG / Retrieval-Augmented Generation
**Not used in this framework.**
**How it works.** An external search system (a vector database or
embedding index) finds the most relevant passages from a large
knowledge base at query time and injects them into the prompt.
**Tradeoffs.** Scales to enormous knowledge bases — thousands of pages,
multiple manuals, entire codebases. But you lose control over exactly
what gets retrieved and what surrounds it. Chunk boundaries may split
a rule in half. Retrieval relevance depends on embedding quality.
**Why the framework skips it.** The framework's knowledge base is
moderate — a small set of rule skills plus reference materials. GATE-
based loading handles that without RAG overhead. RAG also risks
retrieval that splits interdependent rules (rule R14 references rule
R15; a chunk missing the cross-reference is worse than no chunk).
**When to use it (elsewhere):**
- Very large knowledge bases (100+ documents, entire style guides).
- Questions where skills can't be pre-mapped to steps.
- When "good enough" recall is acceptable — combine with Pattern 7 to
catch retrieval errors.
## Pattern 5: Tool-Based Lookup
**How it works.** Skills are exposed as callable tools — commands the
agent runs on demand, like reading a file, running a grep, or invoking
a binary. The agent decides when to invoke them.
**Tradeoffs.** The agent has autonomy to decide when to consult
references. Works well when the agent can reliably judge what it
doesn't know. The risk is skipping: if the tool isn't forced, the agent
may not call it, especially under time pressure or with simpler models.
**How it differs from Pattern 3 (GATE-Based):**
| Aspect | GATE-Based | Tool-Based |
|--------------|-------------------------------|-------------------------------|
| Who decides | Prompt designer | Agent (the model) |
| When loaded | At predefined workflow steps | When the agent chooses |
| Guarantee | Mandatory (GATE = must read) | Optional (agent may skip) |
| Flexibility | Fixed workflow | Adaptive to novel tasks |
**Example in this framework.** A prose-linting workflow that
delegates to Vale would live in [`../tools/`](../tools/) — for
example, `../tools/vale/` with a `run-vale.sh` wrapper. A skill that
loads Vale via Pattern 5 would say: *"When you reach a prose-check
step, call `../tools/vale/run-vale.sh` on the target file and enumerate
findings."* Same shape for an ImageMagick verifier or a Mermaid
renderer. No tool ships in the framework yet; `tools/` is empty.
**When to use it:**
- Exploratory tasks where the reference isn't predictable.
- When the agent model is strong enough to self-direct (Opus-class).
- As a supplement to Pattern 3 for edge cases.
- General-purpose agents (not domain-specific workflows).
**When to avoid it:**
- Compliance-critical workflows — the agent might skip a required check.
- Smaller models that may not reliably self-direct.
- When you need auditable proof every rule was consulted.
## Pattern 6: Hierarchical / Cascading Prompts
**How it works.** Knowledge is split across layers. A base system
prompt, a task-specific agent prompt, and per-step skill files. Each
layer contains only what's relevant at that level.
**Example in this framework — the four-layer chain:**
```
Layer 1 — Harness (../CLAUDE.md, ~2,500 tokens)
Dispatch rules, environment, resource priority.
Always in context.
Layer 2 — Orchestrator (../agents/orchestrator.md, ~4,000 tokens)
Pipeline routing, pre-flight, initial check, verification gates.
Loaded when framework work is dispatched.
Layer 3 — Stage agent (../agents/{name}.md, ~2,000-3,000 tokens)
Workflow steps, skill-to-step mapping, input handling.
Loaded when the orchestrator routes to it.
Layer 4 — Skill (../skills/{skill-name}/SKILL.md, ~2,000-5,000 tokens each)
Detailed rules, examples, reference tables.
Loaded at GATE points inside the stage agent.
```
The harness does not need to know pipeline-specific dispatch details.
The stage agent does not need to know the dispatch logic for other
agents. Each layer sees only what it needs.
**When to use it:**
- Multi-agent systems with an orchestrator.
- When different tasks need different subsets of knowledge.
- When you want to separate "what to do" from "how to do it."
**When to avoid it:**
- Single-agent systems — the layering adds complexity for no benefit.
- When all knowledge is needed at every layer.
## Pattern 7: Multi-Agent Verification
**How it works.** A second pass (or a second agent) checks the first
agent's output against the knowledge base. The reviewer catches errors
the generator missed.
**Example in this framework — the orchestrator's post-agent verification.**
After every stage-agent run, the orchestrator performs independent
checks before presenting results:
```markdown
## Orchestrator Verification
- [x/!] Public/private API: {header}, {export macro}, {conclusion}
- [x/!] \since: {commit} in {tag} (or: agent inferred — REJECT)
- [x/!] Output filename: {algorithm result} matches agent's field
- [x/!] Source text: line numbers match actual file
- [x/!] Proposed fix compliance: {any rule violations found}
```
Each agent declares its own gate list in its definition file; the
orchestrator runs those gates independently. The rule: if the agent's
output has errors, regenerate corrected suggestions rather than
listing errors alongside the flawed output.
This catches a specific failure mode: fixes that address one issue but
introduce another (fixing passive voice while adding wordiness, fixing
grammar while breaking line length).
**When to use it:**
- High-stakes outputs where errors have real cost (published docs,
code patches, compliance reports).
- When the generator agent has known blind spots.
- When verification criteria are concrete and checkable.
**When to avoid it:**
- Low-stakes tasks where speed matters more than precision.
- When verification criteria are subjective.