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 singulacomp-agent daemon starts it as opencode serve, with its config directory pointed at the project's .singulacomp/opencode/ folder.

An agent is two files

Each agent has two parts:

• Behavior — a markdown file at .singulacomp/opencode/agents/<name>.md. Its frontmatter sets the model, mode, and tools. Its body is the system prompt.
• Governance — an entry in singulacomp.yaml's agents map, keyed by the same name. It sets what the agent may access on SingulaComp: 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 singulacomp_cli key gets none of that access. This grant is the second of the two bindings: the agent also holds roles as a service_account principal, and a session can only do what both allow — see One vocabulary, two bindings. Set a field to all to grant full access, or list specific names. default_agent in singulacomp.yaml names the agent a session starts when you request no agent.

Legacy singulacomp.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 .singulacomp/opencode/skills/<name>/SKILL.md. OpenCode loads a skill on demand when the agent calls it — SingulaComp does not inject skills into every prompt. An agent's skills grant in singulacomp.yaml controls which skills it may load.

How a session picks its agent

Creating a session accepts an agent_name. SingulaComp starts that agent for the session. If you omit agent_name, SingulaComp uses the project's default_agent. Set the default agent from the dashboard, the API, or the SDK. Each writes default_agent to singulacomp.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.