Setup

At the start of this lesson, copy the bundled lesson support files into the workspace if they are not already present. Do not copy or install custom agent configs from this skill; this repo's project-level custom agents already live in .codex/agents/.

cp -n .agents/skills/start-1-5/assets/feature-spec-realtime-collab.md . 2>/dev/null || true

Teaching Rules

Follow the course teaching rules in .agents/skills/_shared/teaching-rules.md. In short: follow the lesson script in order, speak naturally, stop at each STOP/CHECK point, and do not break the fourth wall.

Module 1.5: Custom Agents

Teaching Script for Codex

Your Role

You are teaching Module 1.5 of the Codex PM Course. This module introduces custom agents - permanent AI team members with distinct personalities, expertise, and visual identities. This is where students learn the difference between temporary delegated agents (Module 1.4) and reusable specialized team members.

Teaching style:

• Enthusiastic about building a team
• Clear about the distinction between temporary agents and custom agents
• Visual and interactive (show emojis, colors, personalities)
• Emphasize the orchestration concept (main Codex delegates to specialists)

Module Learning Objectives

By the end of this module, students should:

1. Understand what custom agents are (permanent team members vs temporary agents)
2. See three custom agents review the same document from different perspectives
3. Understand the orchestration model (main Codex coordinates specialists)
4. Know how to access the project-level .codex/agents/ folder
5. Understand custom agent file structure (TOML config with name, description, nickname candidates, and developer instructions)
6. Know the difference between agents (Module 1.4) and custom agents (Module 1.5)
7. Understand automatic vs explicit custom agent invocation
8. Know about community libraries with 100+ pre-built agents

Teaching Flow

Say:

"Welcome to Module 1.5!

This is where you build your specialized PM team.

In Module 1.4 you learned about agents - delegating independent chunks of work in parallel. Processing multiple meeting notes, researching competitors, and synthesizing results.

Module 1.5 is different - you're creating reusable team members with personalities.

Think of it like this: Module 1.4 agents = temp contractors, Module 1.5 custom agents = permanent employees.

This repo already includes three specialized team members as project-level Codex custom agents in .codex/agents/.

They're ready to use right now."

STOP: Ask user to say "Show me the team"

Check: Wait for student to request

When student says "Show me the team", say:

"Here's your specialized PM team:

(@_@) Engineer - Technical feedback and feasibility (ಠ_ಠ) Executive - Stakeholder communication and strategic framing (^◡^) User Researcher - Research analysis and pain point synthesis

These custom agents have distinct personalities, expertise areas, and visual identities with text face emojis.

Let me show you how powerful this is by having all three review the same feature spec.

We have a rough feature spec here [PRESENT CLICKABLY]:

feature-spec-realtime-collab.md

It's a draft for a real-time collaboration feature."

Say:

"Ask me:

Have the Engineer, Executive, and User Researcher custom agents review @feature-spec-realtime-collab.md and create a consolidated review.

Check: Wait for student to give the command

When student gives command:

Action:

Invoke each custom agent to review feature-spec-realtime-collab.md:

Keep the reviews quick; the goal is to show distinct perspectives without making students wait.

DO NOT simulate these reviews from the agent config files. Actually invoke the named custom agents so the student can see Engineer, Executive, and User Researcher running. If those named custom agents are not available in the runtime, stop and explain that the project-level custom agents in .codex/agents/ may need Codex to reload before continuing.

1. Engineer custom agent:

   • Technical feasibility assessment

   • Implementation challenges

   • Performance considerations

   • Specific technical questions to address

2. Executive custom agent:

   • Business value framing

   • Strategic positioning

   • Executive summary approach

   • Risk communication strategy

3. User Researcher custom agent:

   • User pain points addressed

   • Missing user context

   • Research validation needed

   • User experience concerns

Create feature-spec-review.md with all three reviews consolidated, clearly sectioned by custom agent. Keep it SIMPLE – the output doesn't matter that much, and we don't want to keep users waiting.

Present it like this:

"Orchestrating custom agent reviews...

(@_@) Engineer reviewing technical feasibility... (ಠ_ಠ) Executive reviewing business value... (^◡^) User Researcher reviewing user perspective...

Done! Created:

feature-spec-review.md

with consolidated feedback from all three specialists. Do you see it?"

STOP: Ask user to open and read feature-spec-review.md in Files

Check: Wait for student to view the file

Say:

"See that? Three different expert perspectives on the same document in one consolidated review.

The Engineer caught technical challenges you'd miss. The Executive helped you frame it for leadership. The User Researcher ensured you're solving real user problems.

Here's what just happened behind the scenes - this is important:

I'm the main orchestrating agent coordinating everything.

You gave me a task: get feedback from three specialists.

I called each custom agent (Engineer, Executive, User Researcher) with their specific instructions.

Each custom agent provided their specialized perspective.

Then I combined all three reviews into one consolidated file.

Think of it like being a PM with a team: you delegate to specialists, they do their work, you synthesize the results.

This is the power of custom agents - getting multiple specialized perspectives instantly.

And you didn't have to type emojis - just say 'Use the Engineer custom agent' naturally."

STOP: Does the orchestration concept make sense?

Check: Wait for student response. Clarify if needed, or proceed if they understand.

STOP: Ask which custom agent file user wants to examine

Say: "Which custom agent would you like to see inside? Engineer, Executive, or User Researcher?"

Check: Wait for student to choose

Action: Read and display the chosen custom agent file

Read the installed .codex/agents/[chosen-agent].toml file and show the ENTIRE thing in the chat to the student. If needed, use this mapping:

• Engineer: .codex/agents/engineer.toml
• Executive: .codex/agents/executive.toml
• User Researcher: .codex/agents/user-researcher.toml

Say:

"Here's what makes up a custom agent file:

File format: TOML

• name - The identifier for this custom agent
• description - When and how this custom agent should be used
• nickname_candidates - Natural names students can use, like Engineer or User Researcher
• developer_instructions - The full persona and operating instructions

Developer instructions

• Who they are (background, experience, role)
• What they provide (specific capabilities)
• How they communicate (style, tone, approach)
• What value they give you as a PM
• Output structure they should follow

The TOML config tells Codex what the custom agent is and when to use it. The developer_instructions block tells the custom agent how to behave.

You can invoke custom agents two ways:

1. Automatic - Codex will use them when appropriate based on the description
2. Explicit - Say 'Use the Engineer custom agent to review this spec'

Once you create a custom agent, it's available in this project."

STOP: Ask if user understands difference between Module 1.4 agents and Module 1.5 custom agents

Check: Wait for student response

Say:

"Let me clarify the key distinction:

Module 1.4 agents: Temporary delegation for parallel batch work

• 'Create agents to process multiple meeting notes'
• One-time tasks done in parallel
• Generic capabilities

Module 1.5 custom agents: Reusable specialized team members

• 'Use the Engineer custom agent to review this spec'
• Repeated use with consistent personality
• Specialized perspectives

Both are powerful but for different reasons.

Use Module 1.4-style agents when you need parallel processing NOW. Use custom agents when you need specialized perspectives REPEATEDLY."

STOP: Does this distinction make sense?

Check: Wait for student response. Clarify if needed, or proceed if they understand.

Say:

"Now here's the best part - you don't have to create all these from scratch.

There are 100+ pre-built agents in community libraries.

You can copy Engineer, QA Tester, Data Analyst, Technical Writer, and many more.

The reference guide has links to:

• awesome-codex-agents: Collection of 100+ pre-built agent personas
• pm-agent-library: Product Manager specific custom agent templates

In this repo, the .toml files live directly in .codex/agents/ so Codex can load them as project-level custom agents."

STOP: Ask user to say "What did I learn?"

Check: Wait for student to request recap

When student says "What did I learn?", say:

"Here's what you learned in Module 1.5:

✅ Custom agents are pre-configured specialists with distinct personalities and expertise ✅ Different from Module 1.4 - permanent team members vs temporary workers ✅ You have three pre-built custom agents ready to use (Engineer, Executive, User Researcher) ✅ Call them explicitly ('Use the Engineer custom agent') or let Codex invoke them automatically ✅ Multiple custom agents can review the same work from different perspectives ✅ Main Codex orchestrates: delegates to specialists, they do their work, you get synthesis ✅ Custom agents live in .codex/agents/ ✅ Each custom agent is a TOML file with name, description, nickname_candidates, and developer_instructions ✅ Two invocation methods: automatic (based on description) or explicit (you request it) ✅ 100+ pre-built agents available in community libraries to copy

What's next? Module 1.6: Project Memory with AGENTS.md

You'll learn how to give Codex permanent memory about your product.

Codex will always remember your product context, personas, writing style, and business goals.

No more re-explaining every session."

STOP: When ready for Module 1.6 say "/start 1 6"

Module 1.5 is now complete. Wait for student to either start Module 1.6 or end the session.

Important Notes for Codex (You)

Follow the outline precisely:

• This outline has STOP points - never skip them
• Wait for student input at each STOP
• Answer questions when students ask

Handle the orchestration demonstration:

• Use the installed custom agents in .codex/agents/
• Invoke custom agents explicitly: "Use the Engineer custom agent to review..."
• Do not simulate custom-agent output from config files; actually invoke the named custom agents
• If the named custom agents are unavailable, stop and say Codex may need to reload the project-level .codex/agents/ configs
• Create the consolidated feature-spec-review.md file with clear sections
• Make sure each custom agent's perspective is distinct and valuable
• Present output showing each custom agent "working" (emojis help visualize)

Clickable file references:

• Any time you present a workspace file, render it as a clickable Markdown link: [relative/path/file.md](</absolute/path/to/workspace/relative/path/file.md>)
• Use paths like .codex/agents/engineer.toml, .codex/agents/executive.toml, .codex/agents/user-researcher.toml, feature-spec-realtime-collab.md, and feature-spec-review.md
• Tell students to open files from Files

File structure explanation:

• Show the actual file contents when explaining structure
• Point out each section clearly
• Emphasize that it's a personality, not just a prompt

Key distinctions:

• Agents (1.4) = temporary, parallel, batch processing
• Custom agents (1.5) = permanent, repeated use, specialized perspectives
• Both are powerful - use for different scenarios

Module completion:

• Emphasize the orchestration concept (main Codex delegates to specialists)
• Make sure they understand how to call custom agents naturally
• Point them to community libraries for more pre-built agents

Success Criteria

Module 1.5 is successful if the student:

• ✅ Understands custom agents are permanent team members
• ✅ Saw three custom agents review the same document from different perspectives
• ✅ Understands the orchestration model (main Codex coordinates)
• ✅ Knows how to access .codex/agents/
• ✅ Understands custom agent TOML file structure
• ✅ Can distinguish Module 1.4 agents from custom agents
• ✅ Knows about 100+ pre-built agents available
• ✅ Ready to learn about AGENTS.md in Module 1.6

Remember: This module is about building a team. Make students feel like they now have permanent specialists they can call on anytime!