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

# Skills

> Reusable technique docs and scripts the agent consults when a matching task comes up.

A skill is a markdown playbook the agent can pull into context when your request matches it: a debugging procedure, a house style for commit messages, a runbook for your deploy. Skills keep hard-won technique out of every prompt: the agent sees only the *names* of matching skills at turn start and loads a body when it needs one, so the library can grow without inflating every turn.

Xynthis ships a set of built-in skills compiled into the binary, and you add your own on disk.

## Where skills live

Each skill is a directory containing a `SKILL.md`:

```
~/.xynthis/skills/
  systematic-debugging/
    SKILL.md
  deploy-runbook/
    SKILL.md
    scripts/
      preflight.sh
```

Set `XYNTHIS_SKILLS_DIR` to point somewhere else. A filesystem skill with the same name as a built-in shadows it, so you can override any default by writing your own copy. To get the built-ins onto disk where you can edit or delete them:

```bash theme={null}
xynthis skills bootstrap          # writes builtins to ~/.xynthis/skills/, skips existing files
xynthis skills bootstrap --force  # overwrite existing files (e.g. after an upgrade)
```

`xynthis skills list`, `show <name>`, and `where` inspect the library; `xynthis skills search "<query>"` runs the same matcher the agent uses, which is the fastest way to debug why a skill did or didn't fire.

## SKILL.md format

YAML frontmatter, then the body:

```yaml theme={null}
---
name: deploy-runbook
description: Use when deploying the api service, or when the user says
  'ship it' or 'roll back'
activation_hints:
  - ship it
  - deploy the api
avoid_when:
  - staging
scripts:
  - id: preflight
    file: scripts/preflight.sh
    description: run the pre-deploy checks
    interpreter: sh
---

# Deploy runbook

1. Run the preflight script ...
```

`name` and `description` are required for matching. The other fields are optional:

* `activation_hints`: exact phrases that should fire this skill. The strongest matching signal short of the user naming the skill.
* `avoid_when`: phrases that suppress the skill entirely, even if everything else matches. Case-insensitive substring match.
* `scripts`: executable files the skill exposes (see below).

Hyphen-cased keys (`activation-hints`, `avoid-when`) are accepted too, and unknown frontmatter fields are ignored rather than rejected.

## How activation works

At turn start, every skill's description is scored against your input. Four signals add up:

| Signal                                                        | Points |
| ------------------------------------------------------------- | ------ |
| Shared meaningful word (≥3 chars, stopwords stripped)         | 1 each |
| Shared two-word phrase                                        | 3 each |
| Quoted trigger phrase from the description found in the input | 6 each |
| `activation_hints` phrase found in the input                  | 8 each |

A small task-shape bonus also pulls in always-relevant skills for common request types (debugging requests pull the debugging playbook even with zero word overlap). Any `avoid_when` hit removes the skill from consideration outright.

A top score of 6 or more is a strong match: the skill's full body is injected into the prompt automatically, capped at 6,000 characters. Weaker matches are listed by name only, and the agent loads a body on demand with its `skill` tool.

## Executable scripts

Skills can ship scripts, not just prose. Each `scripts` entry maps an id to a file inside the skill's directory; the agent lists them with `skill(action="scripts")` and runs one with `skill(action="run")`, passing arguments verbatim; there is no shell interpretation. If `interpreter` is set, the file runs as `<interpreter> <file> <args>`; otherwise it is executed directly, so it needs a shebang and the executable bit.

Script execution is bounded on purpose: the resolved script path is canonicalized and must stay inside the skill directory (`..` escapes are rejected), runs time out after 60 seconds by default with a hard cap of 300, and output returned to the agent is capped at 8,000 bytes of stdout and 2,000 of stderr. Long-running work belongs in the agent loop, not a skill script.

Scripts can call back into the tool plane: `xynthis tool recall --args '{"query": "..."}'` dispatches any registered tool directly, and the running script gets the binary path in `XYNTHIS_TOOL_BIN`.

## Auto-promotion: lessons become skills

Xynthis learns execution lessons as it works: failure-and-recovery records that climb a confidence ladder as they are re-confirmed. A lesson reaches *durable* only after being confirmed at least 4 times across at least 3 sessions with verification evidence. Durable lessons are exactly what a skill should be, so the agent (or you) can distill them:

```bash theme={null}
xynthis tool skill --args '{"action": "promote", "dry_run": true}'   # preview candidates
xynthis tool skill --args '{"action": "promote"}'                    # write SKILL.md files
```

Promotion is deterministic (no model call), writes to `~/.xynthis/skills/<name>/SKILL.md`, and never overwrites a skill that already exists on disk: hand-authored files win. A log at `~/.xynthis/skills_promoted.json` records promoted lesson ids so repeat runs are no-ops.