Skills
Skills are reusable instruction sets for Atuin AI: playbooks, conventions, workflows, or any structured guidance you want the LLM to follow for specific tasks.
How Skills Work
Skills are lazily loaded: Atuin sends only skill names and descriptions to the server. The LLM decides which skills are relevant and loads their full content on demand. You can also invoke skills directly with /skill-name in the TUI.
Creating a Skill
A skill is a directory containing a SKILL.md file with optional YAML frontmatter:
---
name: code-review
description: Conducts a structured code review. Use when the user asks to review code, a PR, or a diff.
---
When reviewing code:
1. **Correctness** — Does the code do what it claims?
2. **Edge cases** — What inputs could break it?
3. **Style** — Does it match the project's conventions?
Current branch: !`git branch --show-current`
Skill Locations
| Scope | Path |
|---|---|
| Project | .atuin/skills/<name>/SKILL.md |
| Global | ~/.config/atuin/skills/<name>/SKILL.md |
Project skills override global skills when names collide. Nested directories are supported for organization (for example, .atuin/skills/ops/deploy/SKILL.md).
Frontmatter
All frontmatter fields are optional. YAML frontmatter goes between --- markers at the top of SKILL.md.
| Field | Default | Description |
|---|---|---|
name | directory name | Display name. Lowercase letters, numbers, hyphens. |
description | first paragraph of body | What the skill does. Sent to the server so the LLM knows when to load it. |
disable-model-invocation | false | If true, the LLM can't discover or load the skill. Only reachable via /name in the TUI. |
Multiline descriptions using the YAML > (folded) or | (literal) syntax are supported.
Invoking Skills
From the TUI
Type /skill-name to invoke a skill directly. Tab-completion is available. Arguments are supported:
The LLM will see the skill content with [Loaded skill: deploy] and [Arguments: patch] headers.
By the LLM
When the LLM determines a skill is relevant to your request, it calls load_skill automatically to fetch the full content. Atuin excludes skills with disable-model-invocation: true from this — the LLM won't see them.
Dynamic Content
Skills support the same shell substitution as user context files:
- Inline:
!command` — replaced with commandstdout` - Block:
```!code block — entire block replaced with scriptstdout
Commands run at skill load time (when invoked), not at discovery time.
Arguments
When invoking a skill with arguments (for example, /deploy patch), the $ARGUMENTS placeholder in the skill body is replaced with the argument string before shell substitution runs:
---
name: deploy
description: Deploy the application
disable-model-invocation: true
---
Deploy $ARGUMENTS to production.
Current status: !`kubectl get deployment $ARGUMENTS`
If the body doesn't contain $ARGUMENTS and you provided arguments, Atuin appends them as ARGUMENTS: <value>.
Description Budget
Atuin sends skill descriptions to the server under a total character budget. It cuts each description to 1024 bytes, then skips any skill whose entry would exceed the budget and continues packing the rest. If Atuin leaves any skills out, it tells the server which ones.