> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symbioticsec.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Symbiotic Code

> Everything you need to be productive with 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

<Card title="Don't" icon="x">
  ```
  Fix the bug in auth
  ```

  -> Too vague: no file, no context, no constraints.
</Card>

<Card title="Do" icon="check">
  ```
  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.
</Card>

### 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.

<Warning>
  Results may vary depending on which models you use.
</Warning>

***

## Agents

Symbiotic Code has 4 agents. Switch between them with `Tab` or the `/agents` command.

| Agent     | What it does                                               | When to use it                                            |
| --------- | ---------------------------------------------------------- | --------------------------------------------------------- |
| **Build** | Full access — files, shell, all tools                      | Default for development work                              |
| **Plan**  | Read-only analysis; asks before any write or shell command | Exploring a codebase or planning a feature or refactor    |
| **Ask**   | Read-only agent for getting answers and explanations       | Understanding code or learning about patterns             |
| **Debug** | Specialized agent for diagnosing and fixing bugs           | Investigating unexpected behavior or tracking down errors |

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

[Learn more about agents](/code/basics/agents)

***

## Command palette

Press `Ctrl+P` or type `/` to open the command palette.

| Command     | What it does                          |
| ----------- | ------------------------------------- |
| `/new`      | Start a fresh session                 |
| `/agents`   | Switch between agents                 |
| `/models`   | Change the active model               |
| `/mcp`      | Enable or disable MCP servers         |
| `/skills`   | Load a skill into the current session |
| `/review`   | Launch a subagent to review your code |
| `/sessions` | Switch between saved sessions         |

[Full command reference](/code/basics/common_commands)

***

## 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.

<Steps>
  <Step title="Create the skill file">
    Place your skill in one of these locations:

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

    Each `SKILL.md` starts with YAML frontmatter:

    ```markdown theme={null}
    ---
    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
    ```
  </Step>

  <Step title="Use it in a session">
    Type `/skills` in the command palette to load available skills, or simply reference it in your prompt:

    ```
    Use the git-release skill to prepare the v2.1.0 release notes.
    ```
  </Step>
</Steps>

[Learn more about skills](/code/configuration/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).

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

<Steps>
  <Step title="Add it to your config file">
    Open (or create) `symbiotic.jsonc` at your project root or `~/.config/symbiotic/symbiotic.jsonc` for a global setup:

    ```jsonc title="symbiotic.jsonc" theme={null}
    {
      "$schema": "https://config.symbioticsec.ai/config.json",
      "mcp": {
        "my-mcp-server": {
          "type": "local",
          "command": ["npx", "-y", "my-mcp-package"],
          "enabled": true
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Symbiotic Code">
    Relaunch Symbiotic Code. Use `/mcp` to confirm the server is connected and enabled.
  </Step>

  <Step title="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.
    ```
  </Step>
</Steps>

[Full MCP documentation](/code/configuration/mcp)

***

## 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:

```json title="symbiotic.json" theme={null}
{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "plugin": ["@my-org/custom-plugin"]
}
```

npm plugins are installed automatically via Bun on next launch.

[Full plugin documentation](/code/configuration/plugins)

***

## Next steps

<Columns cols={3}>
  <Card title="Use Cases" icon="flask-conical" href="/code/use_cases">
    See Symbiotic Code in action with real security-focused scenarios.
  </Card>

  <Card title="MCP Servers" icon="plug" href="/code/configuration/mcp">
    Full reference for local and remote MCP configuration.
  </Card>

  <Card title="Skills" icon="graduation-cap" href="/code/configuration/skills">
    Write and distribute reusable agent instruction sets.
  </Card>

  <Card title="Plugins" icon="puzzle" href="/code/configuration/plugins">
    Extend Symbiotic Code with hooks and custom behavior.
  </Card>

  <Card title="Agents" icon="layers" href="/code/basics/agents">
    Understand Build, Plan, Ask, and Debug agents in depth.
  </Card>

  <Card title="Models & Providers" icon="cpu" href="/code/basics/models_and_providers">
    Configure which AI model and provider you use.
  </Card>
</Columns>