Agents

An agent is a markdown file that defines how OpenCode acts in a session. This page covers agent files, skills, and how a session picks an agent.

OpenCode runs every session

OpenCode, the open-source coding-agent runtime, runs every session. The kortix-agent daemon starts it as opencode serve, with its config directory pointed at the project's .kortix/opencode/ folder.

An agent is two files

Each agent has two parts:

• Behavior — a markdown file at .kortix/opencode/agents/<name>.md. Its frontmatter sets the model, mode, and tools. Its body is the system prompt.
• Governance — an entry in kortix.yaml's agents map, keyed by the same name. It sets what the agent may access on Kortix: connectors, secrets, skills, and CLI actions.

The manifest never sets a prompt, mode, or tool. The .md file never sets platform access. See the manifest reference for every governance field.

Governance is deny-by-default

An agent with no connectors, secrets, skills, or kortix_cli key gets none of that access. Set a field to all to grant full access, or list specific names. default_agent in kortix.yaml names the agent a session starts when you request no agent.

Legacy kortix.toml (v1) projects list agents in an array, not a map, and grant full access by default. Set specific grants to restrict access. See the manifest reference.

Skills give an agent know-how

A skill is a markdown file at .kortix/opencode/skills/<name>/SKILL.md. OpenCode loads a skill on demand when the agent calls it — Kortix does not inject skills into every prompt. An agent's skills grant in kortix.yaml controls which skills it may load.

How a session picks its agent

Creating a session accepts an agent_name. Kortix starts that agent for the session. If you omit agent_name, Kortix uses the project's default_agent. Set the default agent from the dashboard, the API, or the SDK. Each writes default_agent to kortix.yaml and commits the change to the project's default branch.

An agent never exceeds the access of the person or token that started the session.

New or changed agents and skills reach future sessions only after a change request merges them into the default branch. Connect external tools before an agent can use them; see Connectors.