Guide

Context to Agent Tutorial

Use this tutorial when a one-off prompt starts becoming an interface the next session should reuse.

Source: docs/context-to-agent-tutorial.md

Context to Agent Tutorial

Use this tutorial when a one-off prompt starts becoming an interface the next session should reuse.

The builder tutorial applies the development loop to one project slice. This path teaches a narrower composition: turn selected context into a checkable prompt, then decide what should become a skill and what should become a subagent.

flowchart LR
    context[Context pack] --> prompt[Prompt assembly]
    prompt --> run[One real run]
    run --> review[Review failures]
    review --> skill[Project skill]
    review --> subagent[Subagent role]
    skill --> next[Next context pack]
    subagent --> next

The rule is simple: context stays current, prompts assemble the current request, skills preserve repeated procedures, and subagents preserve bounded roles.

Use this when

  • the same prompt shape keeps coming back;
  • the agent keeps needing the same local checklist;
  • reviewers need to see what context was supplied and why;
  • a role should not inherit the main chat's reasoning;
  • a future session should run the workflow without rediscovering it.

Skip this path when the work is genuinely one-off. A single useful prompt is not a skill yet.

Inputs

Bring one real project slice and these starting artifacts:

InputSourceWhy it matters
IntentIntent EngineeringNames the outcome the interface should serve.
Model fitModel-Fit FramingNames the language operation the model should perform.
Context packContext ConstructionSupplies selected facts, provenance, constraints, and stop triggers.
Evidence expectationEvidence and EvalsKeeps the prompt from becoming fluent but unverifiable.

Step 1: Build the context pack

Read Context Construction, then use templates/context-pack.md.

The context pack is the dynamic input to the rest of the path. Keep it current and inspectable:

  • task identity;
  • selected files, transcripts, docs, or decisions;
  • provenance and authority;
  • hard constraints and soft preferences;
  • assumptions to test;
  • stop, dissent, and salvage triggers.

Do not hide project facts inside a skill or subagent. If the fact can go stale, it belongs in the context pack.

Step 2: Assemble the prompt

Read Prompt and Context Assembly, then use templates/prompt-assembly.md.

Separate the layers:

LayerQuestion
Stable instructionWhat rule or behavior should survive across runs?
Dynamic contextWhat current facts does this run need?
ExamplesWhat behavior needs to be made concrete?
Output contractWhat shape must come back?
Fixtures and reviewer checksHow will failure be caught?

Run the prompt once before promoting anything. A prompt that has not failed under review has not taught you what should be preserved.

Step 3: Decide what repeats

After the run, review what was repeated and what was current.

If this repeats...Preserve it as...Because...
inspection sequence, checklist, command order, evidence gate, stop conditionproject skillthe workflow should survive the chat.
independent reviewer, scout, implementer, extractor, domain validatorsubagentthe role needs its own context and output contract.
file paths, current decisions, transcript excerpts, one customer's constraintscontext packthe facts can go stale.
one assembled request for one sliceprompt assemblythe shape has not proved reusable yet.

This is the handoff from prompt authoring to skill and subagent authoring.

Step 4: Promote a workflow to a skill

Read Authoring Skills, then use templates/project-skill.md.

Promote only the reusable procedure:

  • trigger;
  • what to inspect;
  • constraints that change behavior;
  • stop conditions;
  • evidence required;
  • output shape.

Leave run-specific facts behind. The next invocation should combine the skill with a fresh context pack.

Step 5: Split a role into a subagent

Read Authoring Subagents, then use templates/subagent.md.

Create a subagent only when a role boundary improves the work:

  • the reviewer should not inherit the implementer's reasoning;
  • a scout needs to inspect many files without flooding the main context;
  • a specialist needs a narrow tool set;
  • parallel work needs independent outputs;
  • a phase gate needs a cold answer.

If the subagent needs the whole chat to function, the role boundary is not clear enough.

Step 6: Check the composition

Before calling the interface reusable, answer these checks:

CheckPass condition
Context stays currentStale project facts live in the context pack, not the skill or subagent.
Prompt is checkableThe assembled request has success criteria, output contract, and failure cases.
Skill is proceduralIt preserves a repeated workflow, not generic advice.
Subagent is boundedIt has a clear input contract, tool boundary, stop condition, and output shape.
Next session can run itA future agent can combine fresh context with the preserved procedure or role.

Output

By the end, you should have:

  • context pack;
  • prompt assembly;
  • notes from one real run;
  • project skill, if the workflow repeated;
  • subagent, if the role boundary was real;
  • review note explaining what stayed dynamic and what was promoted.
← Builder Loop TutorialEval Tutorial →