Using Symbiotic Code

Walk through the essential Symbiotic Code workflows.

Best practices

How to prompt

The quality of the agent’s response depends directly on how clearly you communicate your intent. A few principles:

Be specific about the goal: say what you want to achieve, not just what to do
Name the files or areas involved: the agent searches your codebase, but pointing it in the right direction saves time and tokens
Declare constraints upfront: mention language versions, frameworks, or coding standards before they become a problem
One task at a time: break complex requests into focused steps rather than asking for everything at once

Don't

Fix the bug in auth

-> Too vague: no file, no context, no constraints.

Do

In @src/auth/login.ts, the login function 
returns 200 even on invalid credentials. 
Fix it to return 401 and add a test.

-> Clear filepath, explicit problems, clear expected behavior.

Provide rich content

There are multiple ways to provide more context to your prompts and get better results:

Reference and include specific files from your project with @ instead of describing where code is.
Paste URLs for documentation and API references.
Paste images directly. Copy/paste or drag and drop images into the prompt. This can be useful to show UI designs or error screenshots.

Results may vary depending on which models you use.

Agents

Symbiotic Code has 4 primary agents. Cycle between them with Tab (Shift+Tab to go back) or pick one with the /agents command.

Agent	What it does	When to use it
Build	Default agent. Uses all tools according to your permissions	Default for development work
Plan	Planning mode: file edits are denied (except plan files in `.symbiotic/plans/`) and the agent is instructed to stay read-only	Exploring a codebase or planning a feature or refactor
Ask	Read-only: can read, search and browse the web, but cannot edit files or run shell commands	Understanding code or learning about patterns
Debug	Evidence-based debugging: instruments code, reproduces the bug, and fixes only with runtime proof	Investigating unexpected behavior or tracking down errors

Primary agents can also delegate work to built-in subagents (general, explore, triage, owasp-security-review). You can call one yourself with @, for example @explore where is the auth middleware?.

Start in Plan agent when working in an unfamiliar codebase, and then switch to Build once you have a clear plan.

Learn more about agents

Command palette

Press Ctrl+P to open the command palette, or type / in the prompt to autocomplete slash commands.

Command	What it does
`/new`	Start a fresh session
`/agents`	Switch between agents
`/models`	Change the active model
`/security-mode`	Switch between permissive, balanced and strict security modes
`/mcps`	Enable or disable MCP servers
`/skills`	Pick a skill to invoke
`/review`	Review uncommitted changes (or a commit, branch or PR) in a subtask
`/sessions`	Switch between saved sessions

Start a message with ! to run it as a shell command directly, without going through the model. Full command reference · Terminal UI guide

Add a Skill

Skills are reusable instruction sets that the agent loads on demand. You install one by creating a SKILL.md file in the right place.

Create the skill file

Place your skill in one of these locations:

.symbiotic/skills/<skill-name>/SKILL.md            ← this project only
~/.config/symbiotic/skills/<skill-name>/SKILL.md   ← available everywhere

.agents/skills/ and .claude/skills/ (in the project or your home directory) are also discovered.Each SKILL.md starts with YAML frontmatter:

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

Use it in a session

Type /skills to pick a skill, or invoke it directly with /<skill-name>. The agent can also load it on its own when relevant, or you can reference it in your prompt:

Use the git-release skill to prepare the v2.1.0 release notes.

Learn more about skills

Add an MCP server

MCPs allow Symbiotic Code to connect to external data sources (e.g. local files, databases), tools (e.g. search engines, calculators) and workflows (e.g. specialized prompts).

Each MCP server adds to the context window. Keep only what you actively use to avoid performance and security overhead.

You can also run symbiotic mcp add to add a server interactively.

Add it to your config file

Open (or create) symbiotic.jsonc at your project root or ~/.config/symbiotic/symbiotic.jsonc for a global setup:

symbiotic.jsonc

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-package"],
      "enabled": true
    }
  }
}

Restart Symbiotic Code

Relaunch Symbiotic Code. Use /mcps to confirm the server is connected and enabled, or /status to see its connection status.

Reference it in your prompt

Call out the MCP by its config name:

Use my-mcp-server to fetch the latest schema and generate TypeScript types.

Full MCP documentation

Add a plugin

Plugins let you hook into Symbiotic Code’s events and extend or modify its behavior. There are two ways to load them: Option 1 — Local file Drop a .js or .ts file into the plugin directory:

.symbiotic/plugins/         ← this project only
~/.config/symbiotic/plugins/ ← available everywhere

Files in these directories are loaded automatically at startup. Option 2 — npm package Add the package name to your config file:

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "plugin": ["@my-org/custom-plugin"]
}

npm plugins are installed automatically on next launch. You can also run symbiotic plugin <module> (add -g for the global config) to install a plugin and add it to your config in one step. Full plugin documentation

Next steps

Use Cases

See Symbiotic Code in action with real security-focused scenarios.

MCP Servers

Full reference for local and remote MCP configuration.

Skills

Write and distribute reusable agent instruction sets.

Plugins

Extend Symbiotic Code with hooks and custom behavior.

Agents

Understand Build, Plan, Ask, and Debug agents in depth.

Models & Providers

Configure which AI model and provider you use.

Basics

Customize

Security

Configuration

Best practices

How to prompt

Don't

Do

Provide rich content

Agents

Command palette

Add a Skill

Add an MCP server

Add a plugin

Next steps

Use Cases

MCP Servers

Skills

Plugins

Agents

Models & Providers

​Best practices

​How to prompt

Don't

Do

​Provide rich content

​Agents

​Command palette

​Add a Skill

​Add an MCP server

​Add a plugin

​Next steps

Use Cases

MCP Servers

Skills

Plugins

Agents

Models & Providers

Best practices

How to prompt

Provide rich content

Agents

Command palette

Add a Skill

Add an MCP server

Add a plugin

Next steps