Skip to main content
Agent skills let Symbiotic Code discover reusable instructions from your repo or home directory. Skills are loaded on-demand via the native skill tool—agents see available skills and can load the full content when needed. You can also browse and invoke skills yourself: run /skills in the TUI to pick one, or type /<skill-name> directly, like a custom command.

​
Place files

Create one folder per skill and put a SKILL.md inside it. Symbiotic Code searches these locations:
  • Project config: .symbiotic/skills/<name>/SKILL.md (or .symbiotic/skill/)
  • Global config: ~/.config/symbiotic/skills/<name>/SKILL.md (or ~/.config/symbiotic/skill/)
  • Project Claude-compatible: .claude/skills/<name>/SKILL.md
  • Global Claude-compatible: ~/.claude/skills/<name>/SKILL.md
  • Project agent-compatible: .agents/skills/<name>/SKILL.md
  • Global agent-compatible: ~/.agents/skills/<name>/SKILL.md
Skill folders can be nested: any SKILL.md below a skills/ directory is picked up.

​
Understand discovery

For project-local paths, Symbiotic Code walks up from your current working directory until it reaches the git worktree. It loads any matching skills/**/SKILL.md in .symbiotic/ and any matching .claude/skills/**/SKILL.md or .agents/skills/**/SKILL.md along the way. Global definitions are also loaded from ~/.config/symbiotic/skills/**/SKILL.md, ~/.claude/skills/**/SKILL.md, and ~/.agents/skills/**/SKILL.md. If two skills share the same name, the one loaded last wins and a warning is logged.

​
Disable Claude/agent-compatible skills

Set one of these environment variables to true or 1 to skip the .claude/ and .agents/ locations (project and global):
  • SYMBIOTIC_DISABLE_EXTERNAL_SKILLS
  • SYMBIOTIC_DISABLE_CLAUDE_CODE_SKILLS
  • SYMBIOTIC_DISABLE_CLAUDE_CODE (also disables other Claude Code compatibility features)
Skills in .symbiotic/ and ~/.config/symbiotic/ are always loaded.

​
Load skills from other places

Use the skills option in your config file to add more sources:
symbiotic.json
  • paths: extra directories scanned for **/SKILL.md. Paths can be absolute, start with ~/, or be relative to your working directory. Missing directories are skipped with a warning.
  • urls: remote skill indexes. Symbiotic Code fetches index.json from each URL, downloads the listed files of every skill that includes a SKILL.md, and caches them in ~/.cache/symbiotic/skills/. Files already in the cache aren’t downloaded again.
The index.json format is:
index.json
Each file is downloaded from <url>/<skill-name>/<file>.

​
Security scanning

Every skill is scanned by the Symbiotic security scanner before it can be used. If the scan reports findings above informational severity, or the scan can’t complete, the skill is blocked. Scan verdicts are cached, so skills aren’t rescanned on every start. Your organization can also allow or deny specific skills from the Symbiotic Portal. Blocked skills:
  • are hidden from the agent and can’t be loaded with the skill tool
  • are shown as Blocked in the /skills dialog
  • aren’t available as /<skill-name> commands

​
Control access with permissions

Skills follow tool permissions with the skill key. Patterns match the skill name:
symbiotic.json
Skills denied with "deny" are hidden from the agent. Setting "skill": "deny" removes the skill tool entirely. You can also set this per agent.

​
Write frontmatter

Each SKILL.md must start with YAML frontmatter containing:
  • name (required): the name used to invoke the skill
  • description (required): shown to the agent so it can decide when to load the skill
A SKILL.md without both fields is ignored. Other frontmatter fields (for example license, compatibility, or metadata) are allowed but not used by Symbiotic Code. Everything after the frontmatter is the skill content given to the agent.

​
Name and describe your skill

Names and descriptions aren’t strictly validated, but for compatibility with other tools we recommend that name:
  • Is 1–64 characters
  • Is lowercase alphanumeric with single hyphen separators, for example git-release
  • Matches the directory name that contains SKILL.md
Keep description short (under 1024 characters) and specific enough for the agent to choose correctly.

​
Example

Create .symbiotic/skills/git-release/SKILL.md like this:
When the agent loads a skill, it also receives the skill’s base directory and a sample of the other files in it, so a skill can reference bundled scripts or templates with relative paths.