agent-yaml-authoring - SKILL.md Agent Skill

name: agent-yaml-authoring description: > Author and validate Superagent declarative YAML agent definitions (apiVersion: superagent/v1, kind: Agent). TRIGGER when: creating a new agent, editing configs/agents/*.yaml, reviewing agent spec fields, or when the user asks "how do I define an agent", "write me an agent yaml", "agent 配置怎么写". DO NOT TRIGGER when: working on workflow DAG nodes (use workflow-dag skill), pure Go backend logic, or infrastructure config. origin: learned tags: [agent, yaml, superagent, declarative, config]

Agent YAML Authoring

Superagent agents are declared as Kubernetes-style YAML manifests. Every file in configs/agents/ is hot-reloaded via fsnotify — no server restart needed.

Minimal Template

apiVersion: superagent/v1
kind: Agent
metadata:
  name: my-agent          # unique slug, used as skill://my-agent reference
  description: "One-line description visible in the UI"
spec:
  type: chat_model_agent  # see Agent Types below
  model: gpt-4o
  system_prompt: |
    You are a helpful assistant.
  tools: []               # builtin/<name> | mcp://<server>/<tool> | skill://<name>

Required Fields

Field	Description
`apiVersion`	Always `superagent/v1`
`kind`	Always `Agent`
`metadata.name`	Unique kebab-case slug
`spec.type`	One of the agent types below
`spec.model`	Model ID (see `configs/models/routing-rules.yaml`)

Agent Types

Type	Description
`chat_model_agent`	Single model with optional tools (uses Eino ReAct when tools present)
`deep_agent`	Extended reasoning, multi-step web search
`supervisor`	Orchestrates sub-agents, routes tasks dynamically
`sequential`	Runs sub-agents in fixed order, pipes output
`parallel`	Fans out to sub-agents simultaneously
`plan_execute`	Plan phase then execute phase
`workflow`	Full DAG workflow engine

Tool URI Schemes

tools:
  - builtin/datetime        # built-in Go skill
  - builtin/calculator
  - mcp://filesystem/read   # MCP server tool
  - skill://code-fix        # another agent as a skill

Interrupt / Resume

spec:
  interrupt:
    enabled: true
  checkpoint:
    backend: redis          # or memory

Sub-Agent Reference (orchestration)

spec:
  type: supervisor
  agents:
    - name: researcher      # must be registered before this agent
    - name: writer

Two-pass build order: leaf agents are built first; orchestration agents resolve spec.agents references from the registry. Declare leaves before supervisors.

Canonical Example

See configs/agents/research-agent.yaml for a complete reference with deep_agent, tools, memory, and interrupt/resume wired up.