Directory structure

Introduction

The operator of a Pilotoo server configures it with files, not code. Agents, model profiles, providers and agent templates live in a .pilotoo/ folder, and skills live in a skills/ folder. Both are read by the server, and both are safe to commit because they never hold a secret.

The layout

Directory.pilotoo/
- Directoryagents/ system agents, one YAML file each
  - orchestrator.yaml
  - analyst.yaml
- Directoryprofiles/ model profiles
  - default.yaml the fallback
  - reasoning.yaml
- Directoryproviders/ named model endpoints
  - deepseek.yaml
- Directorytemplates/ agents copied into each tenant once
  - gaia.yaml
Directoryskills/ one folder per skill
- Directorycognitive-doc-design/
  - SKILL.md

The default location is the repository root. PILOTOO_CONFIG_DIR and AGENT_SKILLS_DIR move them; see Configuration.

An agent

A system agent is shared by every tenant and is read-only. It names a profile, the tools it may call and the skills it may read.

id: analyst
name: Analyst
description: Use to reason through a problem and reach a recommendation.
status: active
runtime:
  systemPrompt: >-
    You are the Analyst. Restate the question, state every assumption and
    end with a clear recommendation.
  profileId: reasoning
  tools: []
  builtinTools: []
  skills: []
  knowledge: []
presentation: {}

tools lists registered tool names. An agent can call a tool only if the host registered it and the agent lists it. See Agents.

A profile

A profile is a named model configuration. model is <provider>:<model id>.

name: Default
model: deepseek:deepseek-v4-flash
params:
  temperature: 0

default.yaml is the model every agent runs on unless it names another profile. See Models.

A provider

A provider is a named endpoint. apiKeyEnv is the name of the environment variable that holds the key.

kind: deepseek
apiKeyEnv: DEEPSEEK_API_KEY

Templates and skills

A template is an agent definition the operator distributes: it is copied into each tenant once, then owned by the tenant. A skill is a folder with a SKILL.md document that the agent reads on demand; it is never executed. See Skills.