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

# Skills

> Add skills to your agents

[Agent skills](https://skills.sh/) 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.

***

## Place files

Create one folder per skill name and put a `SKILL.md` inside it.
Symbiotic Code searches these locations:

* Project config: `.symbiotic/skills/<name>/SKILL.md`
* Global config: `~/.config/symbiotic/skills/<name>/SKILL.md`
* 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`

***

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

***

## Write frontmatter

Each `SKILL.md` must start with YAML frontmatter.
Only these fields are recognized:

* `name` (required)
* `description` (required)
* `license` (optional)
* `compatibility` (optional)
* `metadata` (optional, string-to-string map)

Unknown frontmatter fields are ignored.

***

## Validate names

`name` must:

* Be 1–64 characters
* Be lowercase alphanumeric with single hyphen separators
* Not start or end with `-`
* Not contain consecutive `--`
* Match the directory name that contains `SKILL.md`

Equivalent regex:

```text theme={null}
^[a-z0-9]+(-[a-z0-9]+)*$
```

***

## Follow length rules

`description` must be 1-1024 characters.
Keep it specific enough for the agent to choose correctly.

***

## Example

Create `symbiotic/skills/git-release/SKILL.md` like this:

```markdown theme={null}
---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: symbiotic code
metadata:
  audience: maintainers
  workflow: github
---

## What I do

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

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.
```