Skills

A skill is a reusable playbook you give the agent: a folder with a SKILL.md instruction file and, optionally, a few scripts. When your request matches a skill, the agent loads that playbook and follows it — so you can extend the agent with domain-specific know-how without touching its core.

Think of skills as runbooks the agent reaches for when relevant. A “deploy-staging” skill, a “summarize-invoices” skill, a “scaffold-react-component” skill — each lives on disk, stays out of the way until needed, and runs entirely on your machine.

Developer Preview

Atomic Agent is a Developer Preview. The skills format and CLI work today, but frontmatter keys and commands may still shift between releases. Pin a release if you depend on stable behavior.

Why skills exist

Local models have small context windows. Pasting a long playbook into every prompt would blow the token budget and break KV-cache reuse. Skills solve this with progressive loading:

• At startup, the agent sees only a one-line stub per skill (tag + name + description) in the stable prompt prefix.
• When a request matches, the agent calls skill.view to pull the full body into the session.
• Scripts run only when the agent calls skill.run_script — and that always goes through the approval gate.

The result: dozens of skills can be installed, but the prompt stays small until one is actually used.

Quick start

See what's installed

atomic-agent skill list shows every skill with its enabled/disabled state and source (global vs project).

Add a skill

atomic-agent skill install ./my-skill copies a skill folder into your global skills directory.

Read a skill

atomic-agent skill show <name> prints the SKILL.md body so you can review the playbook.

Hide a skill

atomic-agent skill disable <name> keeps the files on disk but hides the skill from the agent.

Where skills live

Skills are discovered from two locations. Project skills override global skills with the same name.

Scope	Location	Use for
Global	$ATOMIC_AGENT_STATE_DIR/skills/<name>/	Skills shared across all your projects
Project	./.atomic-agent/skills/<name>/	Skills specific to one repository

Project skills shadow global ones

If both a project and a global directory contain a skill named my-skill, the project version wins and the global one is invisible. There is no merging or version comparison.

A handful of starter skills are bundled with Atomic Agent and seeded into the global directory on every boot. Because they are re-seeded each restart, you cannot persist a custom edit to a starter by redefining it globally with the same name — put your override in a project skills directory instead, where it shadows the starter.

Anatomy of a skill

A skill is a folder. Only SKILL.md is required.

my-skill/
├── SKILL.md          # required: frontmatter + Markdown playbook
├── scripts/          # optional: whitelisted scripts the agent may run
│   └── build.sh
└── references/       # optional: static files the playbook points to
    └── checklist.md

SKILL.md frontmatter

The file opens with YAML frontmatter, then a Markdown body that is the actual playbook.

---
name: deploy-staging
description: Build and deploy the web app to the staging environment.
version: 1.0.0
requires_tools:
  - os.shell.run
requires_scripts:
  - deploy.sh
dangerous: true
platforms:
  - darwin
  - linux
---

# Deploy to staging

1. Run `npm run build` to produce the bundle.
2. Run the `deploy.sh` script with the target as the first argument.
3. Confirm the health check at the staging URL returns 200.

Key	Required	Notes
name	yes	Kebab-case (a-z, 0-9, hyphen), 2–64 chars, no leading/trailing hyphen. Must be unique.
description	yes	One line. Renders into the stub the agent sees at startup.
version	no	Free-form version string. Defaults to 0.0.0 when absent — the shared agentskills.io standard does not mandate it.
requires_tools	no	Informational list of tools the playbook expects.
requires_scripts	no	Allowlist of scripts that skill.run_script may invoke.
dangerous	no	Boolean hint flag.
platforms	no	Allowlist of darwin / linux / win32. Omit the key entirely for cross-platform.

Platform filtering happens at load time

A skill with platforms: [darwin] will not appear in the registry on Linux, even if the files are on disk. To support a skill everywhere, omit the platforms key — an empty array is not the same as cross-platform.

How the agent uses a skill

The agent has exactly two skill tools, both invoked during a turn:

• skill.view { name } — loads the full SKILL.md body (minus frontmatter) into the session. The body is cached for the rest of the session, so repeated calls do not regrow the prompt.
• skill.run_script { skill, script, args? } — executes a script declared in requires_scripts. This is always treated as a dangerous operation and routed through the approval gate.

flowchart TD
    Start["User request"] --> Match{"Matches a skill<br/>stub in the catalog?"}
    Match -->|no| Normal["Agent proceeds<br/>with normal tools"]
    Match -->|yes| View["skill.view { name }"]
    View --> Body["Full SKILL.md body<br/>loaded into session<br/>(cached till session end)"]
    Body --> Follow["Agent follows<br/>the playbook"]
    Follow --> NeedScript{"Playbook calls<br/>a script?"}
    NeedScript -->|no| Done["Reply / finish"]
    NeedScript -->|yes| Check["Validate script is in<br/>requires_scripts +<br/>path stays under scripts/"]
    Check --> Approve["Approval gate:<br/>show preview, await y/n"]
    Approve -->|approved| Run["runCommand executes script<br/>(.ts/.js → node, .sh → bash)"]
    Approve -->|denied| Done
    Run --> Done

Script execution rules

When the agent calls skill.run_script, the runtime enforces several guards before anything runs:

• Allowlist only. The script name must appear in the skill’s requires_scripts frontmatter. Arbitrary files in scripts/ cannot be invoked.
• No path traversal. Scripts must live directly under <skill_root>/scripts/. Paths like ../../etc/passwd, absolute paths, or subdirectories are rejected.
• Type by extension. .ts / .js run with node; .sh runs with bash; anything else runs directly (relying on its shebang or executable bit).
• Bounded execution. Scripts run through the shared command runner with a 30-second timeout.
• Always gated. Execution goes through the approval gate with a preview. There is no unapproved path. (Running the agent with --no-approval auto-approves, intended for testing and trusted environments only.)

Managing skills from the CLI

Install / remove

# Install a skill folder into the global skills directory
atomic-agent skill install ./path/to/my-skill

# Overwrite an existing skill of the same name
atomic-agent skill install ./path/to/my-skill --force

# Remove a global skill
atomic-agent skill uninstall my-skill

A local path install is validation plus a recursive copy. Without --force, install fails if a skill of that name already exists globally. install also accepts remote identifiers — see Installing from a registry.

Inspect

# List all skills with enabled/disabled state and source
atomic-agent skill list

# Print a skill's SKILL.md body
atomic-agent skill show my-skill

Enable / disable

# Hide a skill from the agent without deleting it
atomic-agent skill disable my-skill

# Bring it back
atomic-agent skill enable my-skill

Enable/disable mutate the skills.disabled array in config.json. Disabled skills stay on disk and remain visible in the TUI, but the agent cannot skill.view or skill.run_script them — those tools throw SkillNotFoundError.

Installing from a registry

Skills don’t have to come from your own disk. skill install also resolves remote identifiers, and two sources ship out of the box.

ClawHub is the default registry and is enabled by default (skills.clawhub.enabled, API base https://clawhub.ai). GitHub taps are repositories you point at directly; the default taps are anthropics/skills, openai/skills, and vercel-labs/agent-skills.

# ClawHub — the @owner/slug form
atomic-agent skill install @owner/slug

# GitHub — owner/repo, optionally a subpath within the repo
atomic-agent skill install owner/repo
atomic-agent skill install owner/repo/path/to/skill

# Discover what's out there
atomic-agent skill browse                        # ClawHub + configured taps
atomic-agent skill browse --source owner/repo    # one tap only
atomic-agent skill search <query>

# Manage taps (mutates config.json)
atomic-agent skill tap list
atomic-agent skill tap add owner/repo
atomic-agent skill tap remove owner/repo

The security scan

Every remote install is downloaded to a temp directory and passed through a security scanner before anything lands in your skills directory. If the scan returns a dangerous verdict, the install is blocked and you’re told which check fired. You can override it:

atomic-agent skill install @owner/slug --acknowledge-risk

The scanner is a filter, not a sandbox

A skill’s scripts run with the full permissions of the agent process — they read your files and your environment, and nothing isolates them. The scanner catches recognizable patterns; it cannot catch a script that is merely well-written and hostile, and --acknowledge-risk disables even that check.

Install skills the way you’d install any other executable: from authors you actually trust, after reading the scripts. Passing --acknowledge-risk to silence a dangerous verdict means you’ve read the code and decided, not that the warning was noise.

To opt out of ClawHub entirely and rely only on local paths and taps you’ve chosen:

{ "skills": { "clawhub": { "enabled": false } } }

Browse and install from the TUI

You don’t have to drop to the CLI to find a skill. The Skills panel has a built-in hub over the same sources — ClawHub plus your configured taps — reachable with i from the installed list, or straight from the editor:

/skills browse                          # open the hub
/skills search <query>                  # open it on a search
/skills install <owner/repo[/path]>     # install by identifier

Hub rows carry all-time download counts for ClawHub entries (GitHub taps don’t report them). Enter on a row opens a pre-install card with the skill’s SKILL.md so you can read the playbook before anything is written to disk — j / k scroll it, i or y installs, n or Esc backs out.

When the scanner flags a skill — typically because it carries runnable scripts — a confirm appears before the install proceeds. Answering y there is the panel’s equivalent of --acknowledge-risk on the CLI, and it carries the same weight: you are saying you read the scripts. d on an installed row uninstalls, also behind a confirm.

The full key list is in TUI panels.

Configuration and environment

Setting	Where	Effect
skills.disabled	config.json (array of names)	Skills hidden from the agent.
skills.clawhub.enabled	config.json	ClawHub registry, default true.
skills.clawhub.apiBase	config.json	Registry endpoint, default https://clawhub.ai.
skills.taps	config.json (array of owner/repo)	GitHub repositories browsed and searched for skills.
ATOMIC_AGENT_STATE_DIR	env var	Root for the global skills/ directory and runtime state.
ATOMIC_AGENT_STARTER_SKILLS_DIR	env var	Override the source location for bundled starter skills.

The HTTP API exposes the same operations for hosted setups: GET /api/skills, POST /api/skills/install, and POST /api/skills/uninstall. In the TUI, the Skills panel toggles skills live.

Example: a “release-notes” skill

A complete skill that turns recent commits into release notes.

---
name: release-notes
description: Draft release notes from git history since the last tag.
version: 1.0.0
requires_tools:
  - os.shell.run
  - os.git.log
requires_scripts:
  - collect.sh
---

# Draft release notes

1. Run the `collect.sh` script to gather commits since the last tag.
2. Group the output into Features, Fixes, and Chores.
3. Write a concise summary paragraph, then the grouped list.
4. Reply with the formatted notes — do not write any files unless asked.

my-skill/scripts/collect.sh

#!/usr/bin/env bash
set -euo pipefail
last_tag="$(git describe --tags --abbrev=0 2>/dev/null || echo '')"
if [ -n "$last_tag" ]; then
  git log "${last_tag}..HEAD" --pretty='- %s'
else
  git log --pretty='- %s'
fi

Install and use it:

atomic-agent skill install ./release-notes
atomic-agent run
# then ask: "draft release notes for this repo"

The agent recognizes the release-notes stub, calls skill.view to load the playbook, then proposes running collect.sh. You approve the script at the gate, and the agent formats the result into release notes.

Catalog budget

The skill catalog rendered into the stable prefix has a soft budget of 512 tokens (set via ATOMIC_AGENT_SKILLS_CATALOG_BUDGET). If you install many skills, the ones that overflow are dropped silently from the prompt — keep descriptions short and trim skills you don’t use.

Limits

Skills are intentionally simple. They are data plus scripts, nothing more:

• They cannot dynamically register new agent tools.
• They cannot require native modules.
• Scripts inherit the agent process environment — the approval gate is a policy mechanism, not a sandbox.
• Scripts are not sandboxed, so install from sources you trust — see Installing from a registry.