Agents, subagents, skills, tools

Four related concepts: agents, subagents, skills, and tools.

How they fit together

┌─ Your AGENT (the orchestrator) ──────────────────────────────┐
│                                                               │
│   has TOOLS (functions it can call):                          │
│      query_db(sql)        recall(query)                       │
│      update_roadmap(...)  parse_document(...)                 │
│                                                               │
│   loads SKILLS (markdown wisdom about HOW to work):           │
│      agentic-skill-design   roadmap-maintenance               │
│      lessons-learned        deep-research-pattern             │
│                                                               │
│   delegates to SUBAGENTS (specialist agents with their own    │
│      personas, tools, and skills):                            │
│      planner       researcher       writer                    │
│                                                               │
└───────────────────────────────────────────────────────────────┘

Skill vs tool

Skill	Tool
Markdown file (`SKILL.md`) loaded into the agent's context	Python function decorated with `@tool` that runs as code
Captures wisdom — when, why, what discipline	Captures mechanics — inputs, outputs, side effects
Stays useful even when the implementation changes	Tightly coupled to its implementation
Free to write; "expensive" in context tokens every turn it's loaded	"Free" in context (just signature); does work when called

Some skills naturally graduate into tools when they meet the promotion criteria: invoked 3+ times the same way, mechanical, output-stable, interfaces with an external system. The agentic-upskilling skill defines the loop.

Agent vs subagent

The orchestrator is your top-level agent. Its persona is at AGENTS.md, its config at deepagents.toml.

Subagents are specialists the orchestrator delegates to. Each lives in its own folder:

subagents/
├── planner/
│   ├── AGENTS.md          its persona
│   └── deepagents.toml    its model + skills
├── researcher/
│   ├── AGENTS.md
│   └── deepagents.toml
└── ...

Subagents read only the artifact the orchestrator hands them, not full conversation history. This follows the NVIDIA AI-Q pattern: researchers degrade when they see orchestrator-level context.

The 3-role research topology

For deep-research-style work, three roles:

Role	Reads	Produces
Orchestrator	User request	Routes to planner; assembles final
Planner	User request only	Structured JSON plan
Researcher	Planner's plan only	Findings + citations

See deep-research-pattern.

When to add what

You want to...	Add a...
Teach the agent a recurring pattern or discipline	Skill (markdown in `skills/<name>/`)
Give the agent a callable function	Tool (Python `@tool` in `platform/api/.../tools.py`)
Add a specialist persona for delegated work	Subagent (folder in `subagents/<name>/`)
Give the orchestrator new high-level instructions	Edit root `AGENTS.md`

What's next

Memory — how the agent remembers across sessions
Architecture — where all this lives in the layered model