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

​

Skills

​

Table of Contents

• Locations
• How Skills Work
• Skill Commands
• Skill Structure
• Frontmatter
• Validation
• Example
• Skill Repositories

​

Locations

Security: Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.

• Global:
  • ~/.atomic/agent/skills/ (legacy ~/.pi/agent/skills/)
  • ~/.agents/skills/
• Project (only after the project is trusted):
  • .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)

• 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

​

Using Skills from Other Harnesses

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

{
  "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

​

Built-in prompt engineering guidance

​

Skill Commands

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

{
  "enableSkillCommands": true
}

​

Skill Structure

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

See the API reference at `references/api-reference.md` for details.

​

Frontmatter

​

Name Rules

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• No leading/trailing hyphens
• No consecutive hyphens
• Must match parent directory name

​

Description Best Practices

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

description: Helps with PDFs.

​

Validation

• 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

​

Example

brave-search/
├── SKILL.md
├── search.js
└── content.js

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