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.

A project keeps its agents in agents/ and its skills in skills/. OpenCode reads the files only it uses, such as opencode.jsonc, plugins and tools, from harnesses/opencode/.

Projects created before 2026-09 keep agents and skills under .kortix/opencode/. Machine reads both layouts.

An agent is two files

Each agent has two parts:

• Behavior — a markdown file, agents/<name>.md by default. 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 agent name. It sets what the agent may access on Kortix: connectors, secrets, skills, Apps, and Machine permissions. Its file field names the behavior file. The map can live in a file the manifest lists under imports:; default_agent stays in kortix.yaml.

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

Where the agent file lives

agents:
  support:
    file: agents/support.md

• file is a repo-relative path. It must end in .md.
• It must not start with /. It must not contain a . or .. segment.
• Without file, Machine reads agents/<name>.md, then .kortix/opencode/agents/<name>.md.
• When the dashboard saves an agent that has a .md, it writes file with that path.
• The API refuses to change file. To move an agent, move its .md and update file in kortix.yaml in the same commit.

The full path rules are in the manifest reference.

Governance is deny-by-default

An agent with no connectors, secrets, skills, apps, or kortix_permissions key gets none of that access. apps lists the Kortix Apps the agent may open when an App is restricted or private. This grant is the second of the two bindings: the agent also holds a role as a service_account principal — its ceiling — and a session can only do what both allow. See Agent permissions and One vocabulary, two bindings. 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.

Set each grant from the dashboard — Customize → Agents → the agent, one page per grant set on the Access rail: Skills, Connectors, Secrets, Apps, Kortix permissions — or from the CLI with kortix agents scope <agent> (--secrets, --connectors, --apps). The Apps page appears only when the project has the Apps feature flag on. Every path writes the same agents.<name> block in kortix.yaml.

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 skills/<name>/SKILL.md. OpenCode loads a skill on demand when the agent calls the skill tool — Machine does not inject skill bodies 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 acts as itself: its Kortix permissions within its ceiling role, whoever runs it. Starting a session does not lend the agent your own role. See Agent permissions.

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.