A minimal contract for writing effective sub-agent instructions

Codex
1

I’ve been restructuring a large workflow from manual step-by-step steering into an orchestrator + sub-agent setup.

One thing I kept running into: sub-agents perform worse when their instructions carry too much parent-level context.

They seem to work much better when each step file gives them only a minimal local contract:

  • the exact task

  • the exact inputs

  • the exact output artifact

  • the exact decision or transformation required

  • the required output shape, if any

In other words, the sub-agent should only get what it needs to complete its own step correctly.

So I wrote a small skill around that principle for generating and revising sub-agent step instructions. The goal is to keep them local, concrete, and output-driven, instead of mixing in orchestration logic, workflow philosophy, or downstream planning.

Sharing in case this is useful to anyone building orchestrator / sub-agent workflows.

name: subagent-minimal-contract

description: A minimal contract for writing or revising instructions for sub-agents. Keeps each sub-agent local to its own task, inputs, outputs, and required decision.

Subagent Minimal Contract

Use this skill when writing or revising instructions for a sub-agent.

This skill exists to keep sub-agents effective.
A sub-agent should receive only the information needed to complete its own step.
Do not make the sub-agent carry workflow philosophy, orchestration logic, or downstream planning that belongs to the parent agent.

Core rule

A sub-agent instruction should contain only what the sub-agent needs to do its own task correctly.

What to include

A good sub-agent instruction should include only these parts:

  1. the exact task to complete
  2. the exact file or files to read
  3. the exact file or files to write
  4. the concrete decision, transformation, or output the sub-agent must produce
  5. the output shape or required blocks, if the result must follow a structure

What not to include

Do not include:

  • overall workflow philosophy
  • parent-agent orchestration logic
  • why the workflow is structured this way
  • what later steps may do with the output
  • review-gate logic that belongs to the orchestrator
  • discussion of what the sub-agent is not responsible for unless that boundary can be rewritten as a positive task instruction
  • long lists of anti-patterns when a positive instruction can define the target more clearly

Positive-instruction rule

When a constraint is necessary, write it as the correct way to do the task.

Prefer:

  • State one chosen line only.
  • Name the concrete source of the bend.
  • Use one primary chapter center.

Avoid:

  • Do not be vague.
  • Do not keep too many options alive.
  • Do not write the wrong kind of thing.

If a negative rule must exist, keep it short and use it only when a positive formulation cannot protect the task boundary.

Locality rule

Write the instruction so the sub-agent can stay fully local to its own assignment.

That means:

  • the sub-agent should not need to know the whole workflow
  • the sub-agent should not need to infer what the orchestrator is doing
  • the sub-agent should not need to know how acceptance is routed
  • the sub-agent should not need to understand downstream implementation unless the current task directly depends on it

Step-writing rule

When a step file is meant for a sub-agent, prefer this structure:

  1. Purpose
  2. Read inputs from
  3. Save output to
  4. Task
  5. required output blocks or exact output format
  6. block definitions, when needed

Only add more sections if they directly improve the sub-agent’s ability to complete the task.

Task definition standard

A step is well-written for a sub-agent when it answers these questions directly:

  • What am I deciding, discovering, shaping, checking, or transforming?
  • What exact source artifact should I work from?
  • What exact artifact should I produce?
  • What must be true about the result when I am done?

If the step text does not answer those questions clearly, rewrite it.

Minimality test

Before finalizing a sub-agent instruction, remove any sentence that does not materially help the sub-agent:

  • produce a better local result
  • choose between real task alternatives
  • satisfy a required output contract
  • avoid a concrete failure that cannot be prevented more simply

If removing a sentence would not harm task execution, remove it.

Example transformation

Too parent-oriented:

  • STEP 2 is the first real creative step after constraints are locked.
  • The orchestrator should use the review file to decide whether the next step may start.
  • This output should be suitable for STEP 3.

Better sub-agent contract:

  • Read the preflight artifact.
  • Select the one line that should carry this chapter-day.
  • Write the result to <ARTIFACT>_STORY_LINE.md.
  • State one chosen line only.

Default outcome

The result should be a step instruction that is:

  • local
  • concrete
  • output-driven
  • easy for a fresh sub-agent to execute without extra explanation