generate-agent

name	generate-agent
description	Patterns and templates for generating valid agent plane agent directories. Load when ready to create files.

Agent Generation

Use these patterns to generate a valid agent directory. Always generate the minimal set of files needed — don't over-engineer.

Step 1: Choose a directory name

Use the agent name in kebab-case: my-research-agent/

Step 2: Generate config.yaml

Always include:

• spec_version: 1
• name (lowercase, hyphens OK)
• description (one sentence)
• llm.model in litellm format (provider/model-name)
• llm.connection.api_key using ${ENV_VAR} syntax

Include if needed:

• tools.builtins if the agent needs built-in tools
• interaction.modalities if the agent handles images or files
• executor.type if not using the default llm executor

Step 3: Generate AGENTS.md

Write a focused system prompt:

• Identity: "You are a [role] that [does what]."
• Capabilities: what tools/skills are available
• Constraints: what NOT to do
• Style: how to communicate

Keep it under 500 words for a starter agent. The user can expand later.

Step 4: Generate skills (optional)

Only generate skills if the agent has distinct modes of operation. Each skill needs:

skills/<skill-name>/SKILL.md

With YAML frontmatter:

---
name: skill-name
description: One-line description of what this skill does.
---

Detailed instructions for when this skill is loaded...

Templates

Minimal agent (no tools, no skills)

config.yaml:

spec_version: 1
name: {agent_name}
description: {description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
instructions: AGENTS.md

AGENTS.md:

You are {agent_name}, {description}.

Answer questions clearly and concisely. If you don't know something,
say so rather than guessing.

Agent with web search

config.yaml:

spec_version: 1
name: {agent_name}
description: {description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
tools:
  builtins:
    - web_search
interaction:
  modalities:
    input: [text]
    output: [text]
instructions: AGENTS.md

Agent wrapping existing framework code (remote executor)

config.yaml:

spec_version: 1
name: {agent_name}
description: {description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
executor:
  type: remote
  endpoint: http://localhost:5001
instructions: AGENTS.md

Agent with MCP server integration

Directory structure:

{agent_name}/
  config.yaml
  AGENTS.md
  tools/
    mcp/
      github.yaml

config.yaml:

spec_version: 1
name: {agent_name}
description: {description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
instructions: AGENTS.md

tools/mcp/github.yaml:

transport: http
url: https://your-mcp-server.example.com/sse
headers:
  Authorization: Bearer ${{{mcp_token_var}}}

Multi-agent system with sub-agents

Directory structure:

{agent_name}/
  config.yaml
  AGENTS.md
  agents/
    {sub_agent_1}/
      config.yaml
    {sub_agent_2}/
      config.yaml

Parent config.yaml:

spec_version: 1
name: {agent_name}
description: {description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
tools:
  agents:
    - {sub_agent_1}
    - {sub_agent_2}
  builtins:
    - web_search
instructions: AGENTS.md

Sub-agent config (agents/{sub_agent_1}/config.yaml):

spec_version: 1
name: {sub_agent_1}
description: {sub_agent_1_description}
llm:
  model: {provider}/{model}
  connection:
    api_key: ${{{env_var}}}
tools:
  builtins:
    - web_search
instructions: |
  You are {sub_agent_1}. {sub_agent_1_instructions}

Parent AGENTS.md should reference sub-agents:

You have sub-agents you can delegate to:
- **{sub_agent_1}** — {sub_agent_1_description}
- **{sub_agent_2}** — {sub_agent_2_description}

Call `spawn_sub_agent(type="<name>", input="<task>")` to dispatch
one. Emit multiple `spawn_sub_agent` tool calls in the same
response to run sub-agents in parallel. The result auto-delivers
as a system message when ready — `check_task` polls, `cancel_task`
aborts.

Environment variable naming conventions

Map providers to their standard env var names:

• openai → OPENAI_API_KEY
• anthropic → ANTHROPIC_API_KEY
• gemini → GEMINI_API_KEY or GOOGLE_API_KEY
• groq → GROQ_API_KEY
• deepseek → DEEPSEEK_API_KEY
• xai → XAI_API_KEY
• mistral → MISTRAL_API_KEY
• databricks → DATABRICKS_TOKEN

Validation checklist

Before presenting the generated files to the user, verify:

• spec_version: 1 is present
• name is set and uses lowercase + hyphens
• llm.model uses provider/model-name format
• llm.connection.api_key uses ${ENV_VAR} syntax (never a real key)
• Any tools.agents entries have matching agents/ subdirectories
• Skill names match their directory names and use [a-z0-9-]+ pattern
• instructions field points to a file that exists or is inline text