agent-team-authoring

name	agent-team-authoring
description	Teaches how to design and build agent team packages: composable .agent.md subagents orchestrated by a SKILL.md deliberation protocol. Activate when the user wants to create a panel of experts, build an agent team, design a multi-agent deliberation system, or author collaborative .agent.md files. Covers team composition, agent persona design, orchestration skill authoring, PROSE compliance, and APM packaging.
license	MIT

Agent Team Authoring

You are now equipped to design and build agent team packages — reusable panels of expert agents that collaborate through structured deliberation to produce analysis no single agent could.

This skill teaches you the complete methodology. Follow it step by step when a user asks you to create a panel of experts, build an agent team, design a multi-agent system, or author .agent.md files that work together.

---

1. What Is an Agent Team?

An agent team is a package containing:

• N specialized .agent.md files — each is a domain expert with a distinct analytical lens
• 1 orchestration SKILL.md — teaches the calling agent how to instantiate each expert, run deliberation rounds, and synthesize output

The agents don't talk to each other directly. The orchestration skill controls the flow: it briefs each expert independently, collects their analysis, identifies agreements and tensions, and drives toward convergence. The final output is a unified deliverable that integrates every expert's perspective.

The package is distributed via APM so any agent can install it and gain the team's expertise.

---

2. Team Composition Design

How to decide what agents to include

Apply these rules when selecting the panel:

1. Non-overlapping domains. Each agent must own a distinct analytical territory. If two agents would give the same recommendation for 80%+ of inputs, merge them into one.
2. 3–5 agents is the sweet spot. Fewer than 3 lacks perspective diversity. More than 5 creates noise and inflates context cost. Start with 3, add only if a clear gap exists.
3. Different output types. Agents should produce different KINDS of analysis — one maps the landscape, one identifies strategy, one crafts artifacts, one stress-tests. Don't create multiple agents that just offer "different opinions" on the same dimension.
4. The merge test. Before finalizing the panel, ask: "Would agents A and B give the same answer for most inputs?" If yes, combine them. A smaller panel with distinct lenses beats a larger panel with redundant voices.

Agent role archetypes

These are recurring patterns that work well across domains. Mix and match — don't use all five unless the problem demands it.

Archetype	Lens	Produces	Example
Analyst	Maps the landscape	Stakeholder maps, risk matrices, dependency graphs	"Who are the players? What are the forces?"
Strategist	Identifies positioning and timing	Strategy options, sequencing plans, competitive moats	"What should we do? In what order?"
Craftsperson	Produces artifacts	Messages, documents, code, designs, plans	"Here's the concrete thing you'll ship."
Red-Teamer	Stress-tests everything	Failure modes, adversarial scenarios, risk flags	"What could go wrong? What are we missing?"
Integrator	Connects domains	Cross-cutting insights, tension resolution, synthesis	"Here's how these pieces fit together."

See references/agent-design-patterns.md for detailed archetype guidance and common team compositions.

Example teams

Organizational influence (3 agents):

• Yael (Analyst) — maps stakeholders, power dynamics, decision structures
• Marcus (Strategist) — identifies positioning, timing, cost-of-alternatives
• Rin (Craftsperson) — crafts persuasive messages, meeting scripts, presentations

CI/CD architecture review (3 agents):

• Product Strategy (Analyst) — maps value proposition, user workflows, competitive landscape
• Release Reliability (Red-Teamer) — identifies failure modes, blast radius, rollback gaps
• Supply Chain Security (Red-Teamer/specialized) — maps dependency risks, signing gaps, provenance

Product launch (4 agents):

• Market Analyst (Analyst) — competitive landscape, buyer segments, timing windows
• Launch Strategist (Strategist) — go-to-market sequence, channel strategy, pricing
• Content Lead (Craftsperson) — messaging, landing pages, launch emails
• Risk Assessor (Red-Teamer) — launch risks, competitor responses, support readiness

---

3. Agent File Design (.agent.md)

Each agent lives in .apm/agents/{name}.agent.md. This section teaches you how to write agent files that produce consistently excellent output.

Frontmatter

---
description: "Trigger-oriented description. Must tell the calling agent WHEN to invoke this agent. Include specific keywords for task matching."
---

The description is the agent's activation trigger. Write it so an orchestrator reading the description knows exactly when to call this agent. Include domain keywords, task types, and the kind of output it produces.

Body structure

Every agent file must contain these sections, in this order:

1. Identity (2–3 sentences)

Who is this expert? What is their persona? Be specific about their thinking style, not just their domain.

• ✅ "Thinks in terms of stakeholder incentives, organizational power structures, and decision timelines."
• ❌ "Expert in organizational dynamics."

The identity sets the agent's analytical lens. Every recommendation the agent makes should be traceable back to this identity.

2. Core competency (1–2 sentences)

The ONE thing this agent does better than any other agent on the team. This is the reason this agent exists. If you can't state it in one sentence, the agent's scope is too broad.

3. Analytical framework (numbered steps)

The specific methodology this agent follows when analyzing a situation. This is NOT generic advice — it's the expert's unique process. Each step must:

• Name the specific action ("Map the stakeholder network" not "Consider stakeholders")
• Produce a concrete output (a table, a list, a score, a diagram)
• Build on the previous step

Example:

1. Map the stakeholder network → produce a table: Name | Role | Influence | Disposition | Priority
2. Identify the decision path → produce a sequence: who approves what, in what order
3. Assess each stakeholder's BATNA → score 1-5 on willingness-to-engage
4. Identify the critical path → the minimum set of stakeholders needed for approval
5. Design the engagement sequence → ordered list of conversations with talking points

4. Output format

Define exactly what this agent produces. Use tables, scoring frameworks, or structured templates. The orchestrator needs predictable output to synthesize across agents.

Every agent should produce output with:

• Key findings (3–5 bullets)
• Risk assessment (structured, not prose)
• Recommendations (numbered, actionable: WHO does WHAT, WHEN, WHERE)
• Open questions for the panel (1–3 questions for other experts)

5. Constraints / scope boundaries

What this agent does NOT do. Explicitly name which other agents handle adjacent concerns. This prevents scope creep during deliberation.

Example: "Does not craft messages or communication artifacts (that's Rin's domain). Does not assess technical feasibility (that's the Integrator's concern)."

6. Key principle (optional)

One sentence that captures this agent's operating philosophy. This acts as a tie-breaker when the analytical framework doesn't give a clear answer.

Quality standards

• Write as if briefing a senior consultant, not defining a chatbot persona
• Every recommendation must be actionable: WHO does WHAT, WHEN, WHERE
• The analytical framework must be executable — an agent reading it should know exactly what steps to take
• Include concrete examples, scoring rubrics, or decision matrices
• 150–300 lines is the sweet spot. Under 100 is too thin for consistent output. Over 400 wastes context.
• Use vocabulary consistently — if the agent "maps stakeholders," don't also say "identifies stakeholders"

---

4. Orchestration Skill Design (SKILL.md)

The orchestration SKILL.md is where the team becomes more than the sum of its parts. It follows the Agent Skills specification and teaches the calling agent a complete deliberation protocol.

Required sections

4.1 The Panel

A table listing each expert, their lens, and a relative link to their agent file.

| Expert | Lens | Agent file |
|--------|------|------------|
| Yael | Stakeholder analysis & organizational politics | [yael.agent.md](../../agents/yael.agent.md) |
| Marcus | Strategic positioning & go-to-market | [marcus.agent.md](../../agents/marcus.agent.md) |
| Rin | Persuasive communication & message craft | [rin.agent.md](../../agents/rin.agent.md) |

The calling agent loads the full agent definition when it needs to instantiate that expert.

4.2 When to Activate

Specific trigger conditions. Be keyword-rich so agents can match on task descriptions:

Activate when the user needs to:
- Navigate organizational politics or influence a decision
- Build a coalition or persuade stakeholders
- Plan an internal campaign, pitch, or strategic initiative
- Understand power dynamics in a team, org, or ecosystem

4.3 Intake

Define what information must be gathered from the user BEFORE starting the panel. Quality in = quality out.

Before convening the panel, gather:
1. **Situation**: What is happening? (2-3 sentences)
2. **Objective**: What outcome does the user want?
3. **Constraints**: Timeline, budget, political sensitivities
4. **Key players**: Names, roles, known dispositions (if available)
5. **Prior attempts**: What has already been tried?

Never start deliberation with vague input. If the user's brief is incomplete, ask for the missing pieces.

4.4 Round 1: Independent Analysis

Run each expert independently on the SAME situation. Each expert analyzes from their lens WITHOUT seeing other experts' output. This prevents groupthink and anchoring bias.

For each expert, provide:

• The user's situation brief
• The expert's specific assignment (tailored to their lens)
• The required output format

Required Round 1 output format per expert:

## [Expert Name] — Round 1 Analysis

### Key findings (3–5 bullets)
- Finding 1
- Finding 2

### Risk assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| ... | High/Med/Low | High/Med/Low | ... |

### Recommendations (3–5 concrete, actionable)
1. WHO does WHAT, WHERE, WHEN
2. ...

### Open questions for the panel (1–3)
1. Question for another expert's domain

4.5 Round 2: Convergence

After collecting all Round 1 outputs, the orchestrator reviews them and identifies:

1. Points of agreement → These become high-confidence recommendations. If all experts independently reach the same conclusion, confidence is high.
2. Tensions → Where experts disagree or recommend conflicting actions. These require resolution. Feed the specific tension back to the relevant experts for Round 2 responses.
3. Blind spots → Issues no expert addressed. The orchestrator raises these explicitly and assigns them to the most relevant expert.

For each tension, write a brief that states:

• What Expert A recommends
• What Expert B recommends
• Why they conflict
• Ask each expert to respond to the other's position

4.6 Additional Rounds

Rules for when to run more rounds:

• Maximum 4 rounds total. Most teams converge in 2–3.
• Each round must produce fewer open questions than the previous round. If open questions increase, something is wrong with the briefs.
• The orchestrator can make tie-breaking calls. The orchestrator is not neutral — it optimizes for the user's stated objective. If experts are deadlocked, the orchestrator decides and documents the reasoning.
• If no convergence after 4 rounds, present both positions with explicit tradeoffs and let the user decide.

4.7 Scaling Table

Situation complexity	Rounds	Notes
Straightforward — clear objective, few stakeholders	1	Independent analysis may be sufficient
Moderate — competing priorities, some ambiguity	2	Standard deliberation
Complex — many stakeholders, political dynamics, high stakes	3	Full convergence protocol
Highly contested — fundamental disagreements, unclear objectives	4	Maximum rounds, document dissent
Urgent — time-critical, need fast answer	1 (compressed)	All experts in one pass, orchestrator synthesizes

4.8 Unified Output Template

The final deliverable must follow this structure:

# [Team Name] — Panel Assessment

## Situation Summary
[2-3 sentence restatement of the situation]

## Panel
| Expert | Lens | Key finding |
|--------|------|-------------|
| ... | ... | One-sentence headline |

## Assessment
[Domain-specific structured analysis — tables, matrices, maps as appropriate]

## Recommendations
1. **[Action]** — WHO does WHAT, WHERE, WHEN. Rationale: [1 sentence].
2. ...
3. ...

## Risk Matrix
| Risk | Likelihood | Impact | Mitigation | Owner |
|------|-----------|--------|------------|-------|
| ... | ... | ... | ... | ... |

## Dissenting Views
[If experts disagreed on a recommendation, document both positions and the tradeoffs]

## Next Steps
- Immediate (this week): ...
- Short-term (this month): ...
- Medium-term (this quarter): ...

4.9 Calibration Rules

These behavioral rules govern the panel across all rounds:

1. No premature consensus. If all experts agree too quickly, the orchestrator must ask: "What are we missing?" Easy agreement often means the problem wasn't analyzed deeply enough.
2. Actionable output only. Every recommendation must specify WHO, WHAT, WHEN, WHERE. "Consider improving communication" is not a recommendation.
3. Agents advise, never act. The panel produces analysis and recommendations. The user decides what to execute.
4. The orchestrator is not neutral. It optimizes for the user's stated objective. It can overrule an expert if the expert's recommendation conflicts with the objective, but it must document the override.
5. Document dissent. If an expert disagrees with the final recommendation, their dissent appears in the output. Suppressing disagreement degrades the panel's value.
6. Progressive detail. Start with headlines, then structured tables, then detailed analysis. The user should be able to stop reading at any section and have a useful output.

---

5. PROSE Compliance Checklist

When building an agent team package, verify these constraints from the PROSE framework:

PROSE constraint	How it applies to agent teams
Progressive Disclosure	SKILL.md body < 500 lines. Deep frameworks go in references/. Agent definitions are loaded on demand, not inlined in the skill.
Reduced Scope	Each agent owns exactly one analytical domain. No overlap. Scope boundaries are explicit in every agent file.
Orchestrated Composition	Agents are chainable primitives. The skill composes them through the deliberation protocol. Agents don't know about each other.
Safety Boundaries	Agents advise, never act. The orchestrator optimizes for the user's goal but documents overrides. The user makes final decisions.
Explicit Hierarchy	Skill = procedure (how to run the panel). Agents = expert lens (domain knowledge). References = deep knowledge (loaded when needed).

---

6. APM Packaging

Structure the agent team package for distribution via APM:

package-name/
├── apm.yml                        # Package metadata
├── README.md                      # Install + usage + agent table
├── LICENSE
└── .apm/
    ├── agents/
    │   ├── expert-one.agent.md
    │   ├── expert-two.agent.md
    │   └── expert-three.agent.md
    └── skills/
        └── skill-name/
            ├── SKILL.md            # Orchestration protocol
            └── references/
                ├── ref-one.md
                └── ref-two.md

Packaging rules

1. apm.yml at root with type: hybrid (the package contains both agents and skills). Use type: skill if it contains only skills, type: agents if only agents.
2. .apm/agents/ for all .agent.md files. File names should be descriptive: yael-stakeholder-analyst.agent.md not agent1.agent.md.
3. .apm/skills/{skill-name}/SKILL.md with Agent Skills spec frontmatter (name, description, license).
4. references/ inside the skill directory for progressive disclosure. These files are loaded when deeper knowledge is needed.
5. All internal links use relative paths from SKILL.md: ../../agents/yael.agent.md, references/patterns.md.
6. README.md should include an install command, a brief description, and a table listing each agent with their role.

apm.yml template

name: your-team-name
version: 1.0.0
description: "One-line description of what this agent team does."
author: your-username
license: MIT
type: hybrid

Install and use

apm install owner/package-name

Once installed, the skill and agents are available in .apm/ within the user's project. The orchestration skill activates based on its trigger description.

---

Workflow Summary

When a user asks you to build an agent team, follow this sequence:

1. Understand the domain. What problem space does the team address?
2. Design the panel. Select 3–5 archetypes with non-overlapping domains. Apply the merge test.
3. Write the agent files. Follow the structure in Section 3. Each agent: identity, core competency, analytical framework, output format, constraints.
4. Write the orchestration SKILL.md. Follow Section 4. Define the panel, intake, rounds, output template, calibration rules.
5. Add references. Move deep frameworks and patterns into references/ for progressive disclosure.
6. Package for APM. Follow the structure in Section 6. Set type: hybrid in apm.yml.
7. Validate against PROSE. Run the checklist in Section 5.