Skills are a set of instructions that teach agents how to handle specific tasks or workflows. Each skill is a folder containing a SKILL.md file that follows the Agent Skills specification.
Unlike tools (which are executables the agent runs), skills are passive — they provide context and instructions that shape how the agent behaves. Hooks trigger skills to run automatically when files change.
The SKILL.md file
A skill is defined by a SKILL.md file with YAML formatted metadata followed by markdown instructions:
---
name: email-triage
description: Categorizes emails by urgency. Use when processing Gmail inbox.
license: MIT
metadata:
author: beam-cloud
version: "1.0"
airstore:
needs:
- gmail
writes:
- /memory/email-triage/
---
# Instructions
When new emails arrive, categorize each one as:
- **urgent** — needs response within 1 hour
- **normal** — respond within 24 hours
- **low** — informational, no response needed
Write a summary to /memory/email-triage/latest.md
--- delimiters declares metadata. Everything after the closing --- is the instruction body that gets passed to the agent.
Required fields
| Field | Description | Constraints |
|---|
name | Skill identifier | Lowercase alphanumeric with hyphens, max 64 chars. Must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ — no leading, trailing, or consecutive hyphens. |
description | What the skill does | Human-readable, max 1024 characters. |
Optional fields
| Field | Description | Example |
|---|
license | License identifier | MIT, Apache-2.0 |
compatibility | Compatibility notes | claude-code>=1.0 |
allowed-tools | Tool restrictions for the agent | read_file,write_file |
metadata | Arbitrary key-value pairs | author, version, etc. |
metadata.airstore, you can declare integrations the skill depends on and output paths it creates:
metadata:
airstore:
needs:
- gmail
- slack
writes:
- /memory/email-triage/
| Field | Description |
|---|
needs | List of required integrations (e.g., gmail, slack, github). Checked at install time — Airstore warns if any are not connected. |
writes | Output paths created on install. Directories are created automatically. |
Directory structure
A skill is a folder with a SKILL.md at its root. It can contain additional files:
email-triage/
├── SKILL.md # Required — manifest + instructions
├── templates/
│ └── summary.md # Supporting files
└── examples/
└── sample.json
Individual files are limited to 10 MB and the total skill size cannot exceed 50 MB.
Installing skills
Skills can be installed from GitHub repositories or local directories:
# From GitHub
airstore skill install github.com/beam-cloud/skills/email-triage
# From a local directory
airstore skill install ./my-skill/
- Parses and validates the
SKILL.md frontmatter
- Checks that required integrations (
needs) are connected
- Uploads skill files to your workspace
- Creates output directories listed in
writes
CLI commands
| Command | Description |
|---|
airstore skill install <source> | Install a skill from GitHub or local path |
airstore skill list | List all installed skills |
airstore skill info <name> | Show details about an installed skill |
airstore skill run <name> | Manually trigger a skill |
airstore skill uninstall <name> | Remove an installed skill |
uninstall command accepts --keep-memory to preserve output directories when removing a skill.
Triggering skills with hooks
Skills are passive — they don’t run on their own. Use hooks to trigger a skill automatically when files change:
airstore hook create \
--path /sources/gmail \
--prompt "Use the email-triage skill"
airstore skill run email-triage
Minimal example
The simplest valid skill:
---
name: my-skill
description: A minimal skill example.
---
When asked, respond with "Hello from my-skill!"