Skip to main content
Atomic can create skills. Ask it to build one for your use case.

​
Skills

Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Atomic implements the Agent Skills standard, warning about violations but remaining lenient.

​
Table of Contents

​
Locations

Security: Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.
Atomic loads skills from:
  • Global:
    • ~/.atomic/agent/skills/ (legacy ~/.pi/agent/skills/)
    • ~/.agents/skills/
  • Project:
    • .atomic/skills/ (legacy .pi/skills/)
    • .agents/skills/ in cwd and ancestor directories (up to git repo root, or filesystem root when not in a repo)
  • Packages: skills/ directories, atomic.skills, or legacy pi.skills entries in package.json
  • Settings: skills array with files or directories
  • CLI: --skill <path> (repeatable, additive even with --no-skills)
Discovery rules:
  • In ~/.atomic/agent/skills/ and .atomic/skills/ (plus legacy ~/.pi/agent/skills/ and .pi/skills/), direct root .md files are discovered as individual skills
  • In all skill locations, directories containing SKILL.md are discovered recursively
  • In ~/.agents/skills/ and project .agents/skills/, root .md files are ignored
Disable discovery with --no-skills (explicit --skill paths still load).

​
Using Skills from Other Harnesses

To use skills from Claude Code or OpenAI Codex, add their directories to settings: 
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}
For project-level Claude Code skills, add to .atomic/settings.json (legacy .pi/settings.json is also supported): 
{
  "skills": ["../.claude/skills"]
}

​
How Skills Work

  1. At startup, Atomic scans skill locations and extracts names and descriptions
  2. The system prompt includes available skills in XML format per the specification
  3. When a task matches, the agent uses read to load the full SKILL.md (models don’t always do this; use prompting or /skill:name to force it)
  4. The agent follows the instructions, using relative paths to reference scripts and assets
This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.

​
Skill Commands

Skills register as /skill:name commands: 
/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments
Arguments after the command are appended to the skill content as User: <args>. Toggle skill commands via /settings in interactive mode or in settings.json: 
{
  "enableSkillCommands": true
}

​
Skill Structure

A skill is a directory with a SKILL.md file. Everything else is freeform. 
my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

​
SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
```bash
cd /path/to/skill && bun install
```

## Usage

```bash
./scripts/process.sh <input>
```
Use relative file paths from the skill directory (these are bundled skill files, not docs routes): 
See the API reference at `references/api-reference.md` for details.

​
Frontmatter

Per the Agent Skills specification:
FieldRequiredDescription
nameYesMax 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.
descriptionYesMax 1024 chars. What the skill does and when to use it.
licenseNoLicense name or reference to bundled file.
compatibilityNoMax 500 chars. Environment requirements.
metadataNoArbitrary key-value mapping.
allowed-toolsNoSpace-delimited list of pre-approved tools (experimental).
disable-model-invocationNoWhen true, skill is hidden from system prompt. Users must use /skill:name.

​
Name Rules

  • 1-64 characters
  • Lowercase letters, numbers, hyphens only
  • No leading/trailing hyphens
  • No consecutive hyphens
  • Must match parent directory name
Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing, -pdf, pdf--processing

​
Description Best Practices

The description determines when the agent loads the skill. Be specific. Good: 
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
Poor: 
description: Helps with PDFs.

​
Validation

Atomic validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:
  • Name doesn’t match parent directory
  • Name exceeds 64 characters or contains invalid characters
  • Name starts/ends with hyphen or has consecutive hyphens
  • Description exceeds 1024 characters
Unknown frontmatter fields are ignored. Exception: Skills with missing description are not loaded. Name collisions (same name from different locations) warn and keep the first skill found.

​
Example

brave-search/
├── SKILL.md
├── search.js
└── content.js
SKILL.md: 
---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

```bash
cd /path/to/brave-search && bun install
```

## Search

```bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
```

## Extract Page Content

```bash
./content.js https://example.com
```

​
Skill Repositories

  • Anthropic Skills - Document processing (docx, pdf, pptx, xlsx), web development
  • Pi Skills - Upstream skill examples for web search, browser automation, Google APIs, and transcription