Skip to content

Week 6: Custom Agents

This Week's Shift

So far, you have used agents.

This week, you author them.

  • Week 3: choose plan vs. build
  • Week 4: write commands that invoke agents
  • Week 5: write skills agents can discover
  • Week 6: create agents with their own role and permissions

Why Custom Agents?

Use a custom agent when the role needs a different boundary.

Examples:

  • A docs writer that can edit docs but cannot run shell commands
  • A test runner that can run tests but cannot edit files
  • A code reviewer that can read code but cannot change it
  • A migration planner that can inspect a repo but must stay read-only

The point is not personality. The point is delegation with limits.

Agent Anatomy

Every useful agent has five parts:

  1. mode
  2. model
  3. prompt
  4. permissions or tool controls
  5. description

If you can explain these five, you can design agents instead of guessing.

Mode: Primary vs. Subagent

primary

  • You talk to it directly
  • It owns the conversation
  • Good for ongoing work

subagent

  • A primary agent calls it for focused work
  • It returns a report or result
  • Good for isolated specialist tasks

Mental model:

Primary = project lead

Subagent = specialist on call

Primary Agent Examples

Good primary agents:

  • docs-writer
  • migration-planner
  • feature-builder
  • learning-coach

They are useful when the learner or developer wants a direct conversation with that role.

Subagent Examples

Good subagents:

  • code-reviewer
  • test-runner
  • security-auditor
  • dependency-inspector

They are useful when another agent needs a narrow answer:

Review these files and report bugs. Do not edit anything.

Why Subagents Protect Context

Subagents get their own working context.

That means:

  • The test runner can inspect long logs
  • The reviewer can search many files
  • The primary agent receives a summary
  • The main conversation stays focused

Subagents reduce context clutter.

Model

The model is the brain the agent uses.

Different agents can use different models:

  • Strong model for reasoning-heavy review
  • Faster model for simple summaries
  • Cheaper model for repetitive checks

Do not choose the most expensive model by habit. Match model strength to task risk.

Prompt

The prompt defines the role.

Weak prompt:

You help with docs.

Stronger prompt:

You are a documentation writer for beginner developers. Read source files before writing. Explain concepts plainly. Prefer examples over abstract claims. Do not run commands.

The prompt should state job, standards, and boundaries.

Permissions

Permissions define what the agent can touch.

Ask this before creating any agent:

What is the minimum tool access this role needs?

Examples:

  • Docs writer: read and edit docs, no bash
  • Test runner: read and bash, no edit
  • Code reviewer: read/search only, no edit

Good agents are constrained on purpose.

Permission Mindset

Avoid this:

Allow everything because it is convenient.

Prefer this:

Allow only what the agent needs for its job.

Permissions are not a formality. They are the safety boundary.

Description

For subagents, the description helps the primary agent decide when to use them.

Weak:

Helpful reviewer.

Strong:

Reviews code changes for correctness, security risks, missing tests, and maintainability. Reports findings only and does not edit files.

The description is a job posting.

Creating an Agent

Run:

opencode agent create

The guided setup asks for the agent's configuration.

After creation, inspect the generated agent file. Do not treat the wizard as magic. The file is the source of truth.

What To Inspect After Creation

Check:

  • Is the mode correct?
  • Is the model appropriate?
  • Does the prompt state the role clearly?
  • Are permissions minimal?
  • Does the description explain when to use the agent?

If the file is vague, the agent will be vague.

Demo: Docs Writer Primary

Goal:

Create a primary agent for documentation work.

Boundary:

  • Can read source files
  • Can edit markdown docs
  • Cannot run shell commands

Why:

A docs writer should explain and edit. It should not install packages, run tests, or mutate code outside its job.

Demo: Test Runner Subagent

Goal:

Create a subagent for test execution.

Boundary:

  • Can read files
  • Can run test commands
  • Cannot edit files

Why:

The test runner reports evidence. The primary agent decides what to change.

The Code-Reviewer Pattern

Create a read-only subagent:

  • mode: subagent
  • description: reviews code changes
  • Tools: read/search allowed
  • Editing: denied
  • Prompt: findings first, no fixes unless asked

Use it after the build agent makes changes.

When To Create an Agent vs. Command

Create a command when:

  • The task is a reusable prompt
  • The permissions stay the same
  • You want a shortcut like /test file.py

Create an agent when:

  • The role is different
  • The permissions are different
  • The model should be different
  • Other agents may call it later

Lab 6.1 Preview

You will create two agents:

  1. A primary agent, such as docs-writer
  2. A subagent, such as test-runner or code-reviewer

You will use opencode agent create, then inspect and refine the generated files.

Lab 6.2 Preview

You will audit permissions.

You will try to make each agent do something it should not be allowed to do.

Examples:

  • Ask a docs writer to run a shell command
  • Ask a test runner to edit a file
  • Ask a reviewer to modify code

The lab is successful when the boundary holds.

Key Takeaway

Custom agents are not just custom prompts.

They are roles with boundaries.

If you remember one sentence:

Create agents when delegation requires a different role, model, or permission profile.

Next Week

Week 7 combines agents into workflows.

Primary agents will delegate to subagents.

Subagents will report back.

You will start designing multi-agent systems instead of single-agent helpers.