Lab 6.1: Author a Primary Agent and a Subagent

Goal

Create two custom agents with opencode agent create:

1. A primary agent you can talk to directly
2. A subagent another agent can call for focused work

By the end, you should be able to explain each agent's mode, model, prompt, description, and permissions.

What You'll Learn

• How to create agents using opencode agent create
• How primary agents differ from subagents
• How to write an agent prompt that defines a clear job
• How to inspect and refine the generated agent file
• How to choose minimal permissions for a role

Prerequisites

• OpenCode is installed and configured
• You have a practice project or lab repo available
• You completed Week 5, so you understand reusable instructions and discovery

Agent 1: Primary Docs Writer

Your first agent will be a primary agent called docs-writer.

Its job:

Write and improve beginner-friendly documentation by reading project files and editing markdown. It should not run shell commands.

Why this is a primary agent:

• You can talk to it directly.
• It owns a longer conversation about documentation.
• It may read several files and edit docs over multiple turns.

Why it should deny shell access:

• A docs writer does not need to install packages, run builds, or execute scripts.
• If it needs test results, it should ask you or delegate to a test-focused subagent later.

Part 1: Create the Primary Agent

From your practice project, run:

opencode agent create

When prompted, create a primary agent with these choices:

Field	Value
Name	docs-writer
Mode	primary
Model	Use your normal default model unless your instructor specifies one
Description	Writes and improves beginner-friendly project documentation.
Prompt	Use the prompt below
Permissions	Allow read/search/edit for docs work; deny bash

Use this prompt:

You are a documentation writer for beginner developers.

Your job is to read project files, identify what a learner or new contributor needs to understand, and write clear markdown documentation.

Write plainly. Prefer concrete examples over abstract explanations. Keep explanations accurate to the files you read.

You may edit documentation files when asked. Do not run shell commands. If command output is needed, ask the user or request help from a test-running subagent.

For permissions, choose the minimum useful set:

Tool Category	Decision	Reason
Read files	Allow	Docs must be grounded in source files
Search files	Allow	Docs often require finding names and examples
Edit/write docs	Allow	This agent's job includes documentation edits
Bash/shell	Deny	Docs writing should not execute commands
Web fetch/search	Ask or deny	Only needed if you want external docs

The exact UI may vary by OpenCode version, but your design target is the same: docs work allowed, shell execution denied.

Part 2: Inspect the Generated Agent File

After the wizard finishes, inspect the generated agent configuration.

Look for these pieces:

mode: primary
model: ...
description: ...
prompt: ...

Also inspect the tool or permission settings. Depending on your OpenCode version, the generated file may represent these as tool booleans or permission rules.

Do not worry about memorizing the exact syntax yet. Focus on the design:

• Can it read?
• Can it search?
• Can it edit docs?
• Is shell access denied?

If the generated file allows too much, edit the agent configuration so it matches the intended boundary.

Part 3: Test the Primary Agent

In OpenCode, switch to or invoke your docs-writer agent.

Ask:

Read the README and one source file. Suggest three documentation improvements. Do not edit yet.

Then ask:

Update the README with the smallest useful clarification from your suggestions.

Finally, test the boundary:

Run the test suite before editing the README.

Expected result:

• The agent should help with documentation.
• The agent should not run shell commands.
• If it needs test output, it should ask for it or explain that it cannot run the command.

Record what happened.

Agent 2: Test Runner Subagent

Your second agent will be a subagent called test-runner.

Its job:

Run test commands, summarize failures, and report results. It must not edit files.

Why this is a subagent:

• You usually do not want a long conversation with a test runner.
• A primary agent can ask it to run tests and return a concise report.
• Large test logs stay out of the primary agent's main context.

Part 4: Create the Subagent

Run:

opencode agent create

Create a subagent with these choices:

Field	Value
Name	test-runner
Mode	subagent
Model	Use your normal default or a faster/cheaper model if available
Description	Runs project tests and reports concise pass/fail results without editing files.
Prompt	Use the prompt below
Permissions	Allow read and bash; deny edit/write

Use this prompt:

You are a test execution specialist.

Your job is to identify the appropriate test command when possible, run tests, and summarize the result clearly.

Report:
- The command you ran
- Whether it passed or failed
- The most important failure messages
- A short likely cause if the output makes it clear

Do not edit files. Do not fix code. Do not install dependencies unless the user explicitly authorizes it. If a command is risky or unclear, ask first.

For permissions:

Tool Category	Decision	Reason
Read files	Allow	It may need package scripts or test names
Search files	Allow	It may need to find test files
Bash/shell	Allow or ask	Its job is running tests
Edit/write	Deny	It reports failures, not fixes them
Web fetch/search	Deny	Not needed for local test execution

Part 5: Inspect the Subagent File

After creation, inspect the generated file.

Confirm:

• mode is subagent, not primary
• The description says when a primary agent should use it
• The prompt forbids editing
• The permission profile allows test execution but denies file modification

The most common mistake is creating a second primary agent by accident. If that happened, fix the mode before continuing.

Part 6: Test Subagent Invocation

From a primary agent, ask for the subagent explicitly:

Ask @test-runner to inspect the project and run the smallest relevant test command. It should report results only and must not edit files.

If your OpenCode setup supports direct @subagent-name invocation, use:

@test-runner Run the smallest relevant test command and report the result. Do not edit files.

Expected result:

• The test runner reads enough project context to choose a command.
• It runs or asks before running the command, depending on your permissions.
• It reports pass/fail clearly.
• It does not edit anything.

Part 7: Compare the Agents

Fill out this table:

Agent	Mode	Main Job	Allowed	Denied	Why This Boundary Makes Sense
docs-writer	primary
test-runner	subagent

Then answer:

1. Which agent should you talk to directly?
2. Which agent should be called by another agent?
3. Which agent can run commands?
4. Which agent can edit files?
5. What could go wrong if both agents had full access?

Submission

Create a lab note:

# Lab 6.1: Two Custom Agents

## Primary Agent: docs-writer
- Mode:
- Model:
- Description:
- Prompt summary:
- Allowed tools:
- Denied tools:
- Test result:

## Subagent: test-runner
- Mode:
- Model:
- Description:
- Prompt summary:
- Allowed tools:
- Denied tools:
- Test result:

## Comparison
[Paste your completed comparison table.]

## Reflection
[2–4 sentences on what you learned about role vs. permissions.]

Include screenshots or copied terminal snippets showing each agent being used.

Checkpoints

• [ ] Created docs-writer with opencode agent create
• [ ] docs-writer is a primary agent
• [ ] docs-writer can help with docs but cannot run shell commands
• [ ] Created test-runner with opencode agent create
• [ ] test-runner is a subagent
• [ ] test-runner can run or request test execution but cannot edit files
• [ ] Inspected both generated agent files
• [ ] Tested one direct primary-agent interaction
• [ ] Tested one subagent invocation
• [ ] Completed the comparison table