Rules

You can provide custom instructions to Symbiotic Code by creating an AGENTS.md file. This is similar to Cursor’s rules. It contains instructions that will be included in the LLM’s context to customize its behavior for your specific project.

Initialize

To create a new AGENTS.md file, you can run the /init command in Symbiotic Code. You can pass extra focus or constraints as arguments, for example /init focus on the backend services.

You should commit your project’s AGENTS.md file to Git.

/init scans the important files in your repo (README, manifests, build/test/lint config, CI workflows, and existing instruction files such as CLAUDE.md, .cursor/rules/, .cursorrules, or .github/copilot-instructions.md), may ask a couple of targeted questions when the codebase cannot answer them, and then creates or updates AGENTS.md with concise project-specific guidance. It focuses on the things future agent sessions are most likely to need:

build, lint, and test commands
command order and focused verification steps when they matter
architecture and repo structure that are not obvious from filenames alone
project-specific conventions, setup quirks, and operational gotchas
references to existing instruction sources like Cursor or Copilot rules

If you already have an AGENTS.md file, /init will improve it in place instead of blindly replacing it.

Types

Symbiotic Code also supports reading the AGENTS.md file from multiple locations. And this serves different purposes.

Project

Place an AGENTS.md in your project root for project-specific rules. These only apply when you are working in this directory or its sub-directories. At startup, Symbiotic Code walks up from the current directory to the root of the Git repository and loads every AGENTS.md it finds along the way. This means that in a monorepo, starting a session in packages/api/ loads both packages/api/AGENTS.md and the root AGENTS.md.

Nested AGENTS.md files

AGENTS.md files located in sub-directories below the directory you started Symbiotic Code in are loaded on demand: when the agent reads a file, Symbiotic Code looks for an AGENTS.md (or CLAUDE.md) in that file’s directory and each parent directory up to your working directory, and attaches any it has not already loaded to the read result. Each file is only injected once per conversation.

Global

You can also have global rules in a ~/.config/symbiotic/AGENTS.md file. This gets applied across all Symbiotic Code sessions. Since this isn’t committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow. If the SYMBIOTIC_CONFIG_DIR environment variable is set, $SYMBIOTIC_CONFIG_DIR/AGENTS.md is checked first and takes precedence over ~/.config/symbiotic/AGENTS.md.

Claude Code Compatibility

For users migrating from Claude Code, Symbiotic Code supports Claude Code’s file conventions as fallbacks:

Project rules: CLAUDE.md in your project directory (used if no AGENTS.md exists)
Global rules: ~/.claude/CLAUDE.md (used if no ~/.config/symbiotic/AGENTS.md exists)
Skills: ~/.claude/skills/ and .claude/skills/ in your project — see Agent Skills for details

To disable Claude Code compatibility, set one of these environment variables:

export SYMBIOTIC_DISABLE_CLAUDE_CODE=1        # Disable ~/.claude/CLAUDE.md and Claude Code skills
export SYMBIOTIC_DISABLE_CLAUDE_CODE_PROMPT=1 # Disable only ~/.claude/CLAUDE.md
export SYMBIOTIC_DISABLE_CLAUDE_CODE_SKILLS=1 # Disable only .claude/skills (also disables .agents/skills)

These variables do not affect a project-level CLAUDE.md, which is always used as a fallback when no AGENTS.md exists.

In the VS Code extension, Claude Code files are not loaded by default. Enable Load Claude Code Files in Settings > Agent Behaviour > Rules (requires a restart).

Precedence

When Symbiotic Code starts, it looks for rule files in this order:

Local files by traversing up from the current directory to the Git root: AGENTS.md, then CLAUDE.md, then CONTEXT.md (deprecated)
Global file at $SYMBIOTIC_CONFIG_DIR/AGENTS.md (if set), then ~/.config/symbiotic/AGENTS.md
Claude Code file at ~/.claude/CLAUDE.md (unless disabled)

The first matching file name wins in each category: one local file name (all matching files up the tree are loaded), and one global file. For example, if you have both AGENTS.md and CLAUDE.md, only AGENTS.md is used. Similarly, ~/.config/symbiotic/AGENTS.md takes precedence over ~/.claude/CLAUDE.md. Local and global rules are both loaded; they don’t replace each other.

Other tools’ rule files such as .cursorrules, .cursor/rules/, .github/copilot-instructions.md, or GEMINI.md are not loaded automatically. Add them through instructions (see below).

Setting SYMBIOTIC_DISABLE_PROJECT_CONFIG=1 disables local rule files (and relative instructions paths, unless SYMBIOTIC_CONFIG_DIR is set).

Custom Instructions

You can specify custom instruction files in your symbiotic.json or the global ~/.config/symbiotic/symbiotic.json. This allows you and your team to reuse existing rules rather than having to duplicate them to AGENTS.md. Example:

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Each entry can be:

A relative path or glob: matched in the current directory and in every parent directory up to the Git root
An absolute path or glob, or a path starting with ~/
A remote URL (http:// or https://)

You can also use remote URLs to load instructions from the web.

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "instructions": ["https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}

Remote instructions are fetched with a 5 second timeout. If a URL fails to load, it is silently skipped. All instruction files are combined with your AGENTS.md files. When several config files define instructions, the lists are merged (not replaced).

Referencing External Files

While Symbiotic Code doesn’t automatically parse file references in AGENTS.md, you can achieve similar functionality in two ways:

Using symbiotic.json

The recommended approach is to use the instructions field in symbiotic.json:

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "instructions": ["docs/development-standards.md", "test/testing-guidelines.md", "packages/*/AGENTS.md"]
}

Manual Instructions in AGENTS.md

You can teach Symbiotic Code to read external files by providing explicit instructions in your AGENTS.md. Here’s a practical example:

AGENTS.md

# TypeScript Project Rules

## External File Loading

CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.

Instructions:

- Do NOT preemptively load all references - use lazy loading based on actual need
- When loaded, treat content as mandatory instructions that override defaults
- Follow references recursively when needed

## Development Guidelines

For TypeScript code style and best practices: @docs/typescript-guidelines.md
For React component architecture and hooks patterns: @docs/react-patterns.md
For REST API design and error handling: @docs/api-standards.md
For testing strategies and coverage requirements: @test/testing-guidelines.md

## General Guidelines

Read the following file immediately as it's relevant to all workflows: @rules/general-guidelines.md.

This approach allows you to:

Create modular, reusable rule files
Share rules across projects via symlinks or git submodules
Keep AGENTS.md concise while referencing detailed guidelines
Ensure Symbiotic Code loads files only when needed for the specific task

For monorepos or projects with shared standards, using symbiotic.json with glob patterns (like packages/*/AGENTS.md) is more maintainable than manual instructions.

Basics

Customize

Security

Configuration

Initialize

Types

Project

Nested AGENTS.md files

Global

Claude Code Compatibility

Precedence

Custom Instructions

Referencing External Files

Using symbiotic.json

Manual Instructions in AGENTS.md

​Initialize

​Types

​Project

​Nested AGENTS.md files

​Global

​Claude Code Compatibility

​Precedence

​Custom Instructions

​Referencing External Files

​Using symbiotic.json

​Manual Instructions in AGENTS.md

Initialize

Types

Project

Nested AGENTS.md files

Global

Claude Code Compatibility

Precedence

Custom Instructions

Referencing External Files

Using symbiotic.json

Manual Instructions in AGENTS.md