PTENES
MODULE 2.2 ¡ Track 2 ¡ Building in practice

🎯 The description is the trigger

The field description isn't a summary — it's the selection algorithm from the conductor. One wrong word and the agent never triggers. One right word and it triggers at the right time, every time.

7
Topics
~30
Minutes
Practical
Level
Config
Type

When you type a request, the conductor reads your message and then reads the descriptions of all the agents that exist. It asks an implicit question: "does any of these texts match what the user asked for?" If it matches, the agent launches. If it doesn’t—even if the agent is perfect for the task—it stays quiet. The description is the only link between your request and the right specialist.

User prompt "review the auth code" ❌ Weak description "Agent for code review." ✅ Strong description "Review diff after changes in auth/ payments. Use proactively." agent doesn't trigger orchestrator didn't match the context agent triggers reviews the diff, delivers a report

↑ Same user message, two agents with different descriptions — opposite results.

Detailed content

1

🔍 Why the description triggers

The orchestrator doesn’t have a catalog of agents memorized. Each turn, it reads your prompt and the fields description of all available agents. The decision to invoke one or not is a semantic match between what you asked for and what the description describes — it’s not a name, not an emoji, not a title.

⚙️ How the conductor processes

1

You send: "review the payment code before deploy".

2

The orchestrator scans the descriptions of all active agents.

3

If a description says "after changes to payments, use proactively" — it fits. Fire it up.

4

If the description only says "review agent" — too vague to match. Silence.

What it is:

The conductor reads the description every turn to decide which agent to use. It's the only text that guides automatic selection.

Why learn:

Agents with vague descriptions are invisible to the orchestrator. Without understanding the mechanism, you create agents that never appear and don't know why.

Key concepts:

Semantic matching ¡ read on each turn ¡ description as a routing algorithm.

📖
Handles
each turn
🧲
Combine
with the request
⚡
Triggers
automatically
🔇
Mutes
if it’s available
2

⚖️ Weak × strong: what separates the two

A description weak says what the agent is. A description strong says when to use e for what. The difference seems subtle, but it’s the distance between an agent that never fires and one that fires at exactly the right time.

❌ Weak descriptions

  • ▸"Agente para revisĂŁo de cĂłdigo."
    — vague, with no trigger; fires for everything or nothing
  • ▸"Helper de programação."
    — so broad that it competes with any agent
  • ▸"Especialista em segurança."
    — a title with no condition: the orchestrator doesn’t know when
  • ▸"Faz anĂĄlises."
    — one word that covers everything, and therefore covers nothing

✅ Strong descriptions

  • ▸"Revisa diffs em auth/pagamentos. Use proactively apĂłs mudanças nessas ĂĄreas."
    — domain + condition + instruction for when to use it
  • ▸"Pesquisa na web e indexa fontes. Acione quando o usuĂĄrio precisar de dados externos ou quiser verificar fatos."
    — a clear, noncompetitive use case
  • ▸"Gera e revisa planos de implementação. Use proactively antes de qualquer tarefa de desenvolvimento grande."
    — "before" defines the exact moment
What it is:

The structural difference: a weak one describes identity; a strong one describes a use case.

Why learn:

Weak descriptions create agents that never trigger (underuse) or trigger for everything (over-triggering). A strong description is precise.

Key concepts:

Identity vs. situation · conditional trigger · “Use proactively” as a timing instruction.

3

⏱️ "Use proactively" — the explicit timing

The phrase Use proactively in the description is a direct instruction to the conductor: "don't wait for the user to ask explicitly — trigger when the context fits". Without it, the conductor may hesitate and fail to call the agent even when the context is perfect.

💡 Anatomy of a description with timing

description: Reviews the current diff for bugs and security flaws.
Use proactively after any change in auth, payments or sessions.
1 — What

"Review the diff…" — the task itself.

2 — When (trigger)

"Use proactively after…" — the explicit timing.

3 — Domain

"auth, payments, sessions" — narrows the scope.

⚡ Practical tip

Use "Use proactively" only when you want automatic triggering. For agents that should only be called by name (@nome), omit the sentence — the orchestrator will then wait to be explicitly invoked, without stepping in where it wasn’t called.

What it is:

The "Use proactively" instruction in the description authorizes the orchestrator to launch the agent without an explicit user request.

Why learn:

Without this pattern, valuable agents sit idle. Overusing it makes everything fire at once—which is undesirable.

Key concepts:

Proactive vs. reactive ¡ "@name" for manual invocation ¡ timing as a dimension of the description.

4

🔥 Misfires: when the agent triggers incorrectly

There are two types of misfire: more (triggers when it shouldn't) and less (doesn’t trigger when it should). Both have the same cause — the description doesn’t describe the use case precisely enough.

🔊 Misfire A more — over-triggering

  • Reason: description that's too broad or "Use proactively" without domain restrictions.
  • Symptom: the agent shows up in requests that have nothing to do with it.
  • Example: "Review code. Use proactively." → triggers for any mention of code.
  • Fix: add a domain constraint — "Reviews diffs in auth/payments. Use proactively after changes in these areas."

🔇 Misfire A less — under-triggering

  • Reason: description that's too specific, without synonyms, or without "Use proactively".
  • Symptom: the agent never shows up, even when it's ideal for the task.
  • Example: "Review agent." → the orchestrator doesn’t connect the description with the request.
  • Fix: expand the vocabulary and add a trigger — "Review diffs. Use proactively after changes."

How to diagnose a misfire

1

Observe the behavior

Did the agent fire when it shouldn’t have, or should it have fired but didn’t appear?

2

Read the current description

Ask: if I were the conductor, would this text tell me when use this agent?

3

Adjust the trigger or the domain

To get more: add a constraint. To get less: add "Use proactively" and expand the vocabulary.

What it is:

Two failure patterns—the agent triggers too often (broad description) or too rarely (vague description/no trigger).

Why learn:

Misfires are the main cause of distrust in the system. Recognizing the type speeds up the fix to seconds.

Key concepts:

Over-triggering vs. under-triggering ¡ domain as a filter ¡ iterative diagnosis.

5

💥 Skill × agent collision: the plan-roaster case

Skills (files in .claude/commands/) and agents (files in .claude/agents/) can conflict when both have semantically similar descriptions. The orchestrator sometimes selects one when the user wanted the other. The case plan-roaster illustrates this problem and how to solve it.

📌 The plan-roaster case

❌ Before: description that conflicted

name: plan-roaster
description: Analyzes and critiques
  implementation plans.
tools: Read

Problem: “analyze plans” also matches the /plan skill → collision.

✅ Next: a surgical description

name: plan-roaster
description: Critiques plans
  of ready-to-use implementations,
  looking for gaps and risks.
  Use after a plan to be
  generated, not during.
tools: Read

Fix: "after a plan is generated" distinguishes it from /plan (which creates, not critiques).

🧪 How to detect collisions

  • →Ask the conductor: "list the agents and skills that fit 'create a plan'".
  • →If two have similar semantics, one of them needs a more specific description.
  • →What sets them apart: skills are actions triggered by the user; agents are automatic workers.
What it is:

A collision happens when an agent's description and a skill's description overlap semantically — the orchestrator chooses one, but you wanted the other.

Why learn:

As the roster of agents grows, collisions are inevitable without discipline in the description.

Key concepts:

Semantic overlap · skill vs. agent · “after” as a temporal scope separator.

6

🔄 Iterate: ask why it didn't trigger

The orchestrator is your ally in troubleshooting. When an agent doesn’t trigger as expected, the fastest strategy is ask directly to the orchestrator why it didn't use that agent — and ask it to propose a corrected description.

Prompt 1 — under-triggering diagnosis paste into chat 
Por que o agente [nome] nĂŁo disparou no meu Ăşltimo pedido?
Leia a description dele e explique o mismatch.
Depois proponha uma description corrigida.
Prompt 2 — diagnose over-triggering paste into chat 
O agente [nome] disparou quando eu pedi "[pedido X]",
mas nĂŁo queria isso. Leia a description e diga por que
combinou. Reescreva para evitar esse over-disparo.

🔍 The iteration loop

1. Does it trigger incorrectly? → 2. Ask the orchestrator → 3. Edit description → 4. Test again → ✓ Adjusted
What it is:

The diagnostic flow: ask the conductor about the mismatch, get a suggestion, edit, test.

Why learn:

Trying to guess the problem without asking the maestro is slow. It has access to the description and context — use that.

Key concepts:

Assisted diagnosis ¡ short loop ¡ the orchestrator as a detective investigating its own selection.

7

🐛 Closing quotes in YAML — the real bug

Agent frontmatter is YAML. YAML has hidden rules about quotation marks and line breaks. The most common (and invisible) bug is a unclosed quote or incorrect indentation that makes the parser cut the description off halfway through — the agent loads, but the trigger is truncated.

.claude/agents/code-reviewer.md — before/after example YAML + Markdown
❌ Buggy description (unclosed quote)
---
name: code-reviewer
description: "Revisa o diff após mudanças
  em auth e pagamentos. Use proactively
  após qualquer alteração nessas åreas.
tools: Read, Grep
---

# Code Reviewer
Revisa o diff do repositĂłrio atual...

Bug: unclosed quotes in " never closed. The YAML parser reads everything up to the next quotation mark (which doesn't exist) — the description gets truncated or the entire front matter breaks.

✅ Correct description (no quotes, or closed quotes)
---
name: code-reviewer
description: Revisa o diff após mudanças
  em auth e pagamentos. Use proactively
  após qualquer alteração nessas åreas.
tools: Read, Grep
---

# Code Reviewer
Revisa o diff do repositĂłrio atual...

Fix: use a YAML block scalar (no quotes, consistent indentation). The description is read in full.

❌ Avoid

  • • Unclosed quotes
  • • Colons without quotes in the middle of a sentence
  • • Mixed indentation (tab + space)
  • • Continuation lines without a leading space

✅ Do this

  • • Block scalar: no quotes, 2-space indentation
  • • Test with python -c "import yaml; yaml.safe_load(open('agent.md').read())"
  • • One sentence per line in continuations

🔍 Diagnostics

  • • Agent loads but never triggers? Check the YAML.
  • • Ask the maestro: "read the frontmatter of [agent.md] and validate the YAML".
What it is:

Silent YAML bug that truncates the description — the agent exists, but the trigger is broken.

Why learn:

It’s the hardest bug to notice: the file is valid, the agent loads, but its behavior changes without warning.

Key concepts:

YAML block scalar ¡ frontmatter parsing ¡ validation before trusting the trigger.

💬

Prompts ready to use now

Paste these prompts directly into the orchestrator to diagnose and fix descriptions.

Prompt 1 — fix a description that doesn’t trigger diagnosis 
Por que o subagente [nome] nĂŁo disparou nesse prompt?
Leia o arquivo .claude/agents/[nome].md, analise a
description e diga onde estĂĄ o mismatch.
Depois reescreva a description para consertar.
Prompt 2 — check for a skill × agent conflict prevention 
Liste todos os agentes e skills cujas descriptions
combinam com "[pedido X]". Se mais de um combinar,
aponte a colisĂŁo e sugira como diferenciar cada um.
Prompt 3 — validate front matter YAML debug 
Leia o arquivo .claude/agents/[nome].md e valide o
frontmatter YAML. HĂĄ aspas nĂŁo fechadas, dois pontos
no meio de strings sem aspas, ou indentação mista?
Se sim, corrija e mostre o frontmatter vĂĄlido.
🖥️

Simulated screen: diagnosing a description

See how the diagnostic loop looks in practice—the user asks the orchestrator to explain why the agent didn’t launch and gets the corrected description.

claude code ¡ description diagnosis T2 ¡ M2.2
you Why didn't the code-reviewer trigger when I asked "review auth.js"?
orchestrator
I read the file .claude/agents/code-reviewer.md.
Current description: "Agent for code review."
Problem: too generic—it doesn’t specify a domain or a trigger condition.
Proposed corrected description:
Reviews diffs for bugs and security flaws.
Use proactively after changes to auth, payments, or sessions.
you Apply this description to the file.
orchestrator ✓ .claude/agents/code-reviewer.md updated.
Complete loop in < 1 minute ¡ the next request will trigger automatically

↑ Illustrative terminal recreation. The maestro has access to the agent file and can propose the fix directly.

🎯

Exercise: rewrite a weak description

Given the description below, rewrite it so the agent triggers at the right time without over-triggering. Use the three dimensions you learned: what, when e domain.

Original description (weak)

name: deploy-guard
description: Agent that helps with deployments.
tools: Bash, Read

How to do it

  1. Imagine what useful things this agent would do during a deploy (e.g., check environment variables, validate Docker, check for pending migrations).
  2. Define when do you want it to appear automatically — before, during, or after deploy?
  3. Restrict the domain — it should trigger for any mention of code or only for explicit deploy requests?
  4. Write the description in 2–3 lines, including "Use proactively" with the specific condition.

✅ Verification criteria

Your description is good when:

  • →A colleague can tell in 5 seconds when this agent fires.
  • →It no goes with generic requests like “help with code” or “look at this file.”
  • →It yes goes with “deploy feature X” or “I’m going to push to production.”
  • →The YAML is valid: no stray quotation marks, indentation with 2 spaces.

Example of a possible response

name: deploy-guard
description: Checks deploy prerequisites:
  environment variables, pending migrations
  and Docker configuration. Use proactively
  when the user mentions deploy, upload
  for production or feature pushes.
tools: Bash, Read

Observe: what ("check prerequisites"), when ("mention deploy/release/push"), and the specific domain.

✅ Module summary

✓
Description is the router — the orchestrator reads the description every turn to decide whether to trigger the agent.
✓
Weak vs. strong — weak describes identity; strong describes when use.
✓
"Use proactively" — enables automatic invocation; omit it when you want manual invocation with @name.
✓
Two types of misfire — too much (broad description) and too little (vague description). Each has its own fix.
✓
Skill × agent collision — the plan-roaster case shows how "after" a plan is generated differentiates the two.
✓
Iterate with the conductor — ask the conductor to explain the mismatch; it proposes the corrected description.
✓
Close quotes in YAML — use a block scalar without quotes; open quotes silently truncate the trigger.

Next module:

2.3 — The body is the brain. What goes in the .md file body and how it defines the agent's actual behavior.

← Previous module Next module →