Skip to content
Ash

Skills

Skills are reusable instruction files that teach Ash how to run a workflow. A skill is instructions, context, and optional helper files. It is not a compiled plugin.

Skills In 30 Seconds

Use a skill when you want Ash to repeat a workflow reliably:

  • Multi-step tasks with specific order.
  • Domain-specific behavior (for example, your team’s deploy playbook).
  • Guardrails around which tools are allowed.
  • Subagent execution with isolated iterations and context.

When a skill is used:

  1. Ash reads SKILL.md.
  2. Ash launches a skill subagent from that definition.
  3. The skill subagent runs its own tool-and-LLM loop.
  4. Ash returns results as part of the normal conversation.

Where Skills Should Live

Use workspace skills as the default for anything project-specific.

Canonical location:

~/.ash/workspace/skills/<skill-name>/SKILL.md

Inside the sandbox runtime, that same directory appears at:

/workspace/skills/<skill-name>/SKILL.md

Other skill types:

  1. Built-in skills: shipped with Ash.
  2. Installed skills: added from external repos or local sources.

Precedence when names collide: workspace > installed > built-in.

Built-in skills are packaged source skills (not a separate plugin model). They use the same SKILL.md contract and runtime behavior as installed/workspace skills. In this repo, they live at:

src/ash/skills/bundled/

See:

  • src/ash/skills/bundled/README.md

Create Your First Skill

Terminal window
# 1) Scaffold a new skill folder in workspace
ash skill init my-skill --resources scripts,references


# 2) Edit the generated instructions
$EDITOR ~/.ash/workspace/skills/my-skill/SKILL.md


# 3) Validate format and frontmatter
ash skill validate ~/.ash/workspace/skills/my-skill/SKILL.md


# 4) Confirm it's discoverable
ash skill list --source

Generated directory shape:

  • Directorymy-skill/
    • SKILL.md Required: main instructions
    • Directoryscripts/ Optional: helper scripts
      • …
    • Directoryreferences/ Optional: longer docs for context
      • …
    • Directoryassets/ Optional: extra files
      • …

SKILL.md Template

Use this as your starting point:

---
# Required. One-line summary shown when Ash considers this skill.
description: Triages GitHub issues for a repo


# Optional. Override displayed name (default: folder name).
name: github-triage


# Optional. Restrict tools this skill can call (empty = all available).
allowed_tools:
  - bash
  - web_fetch


# Optional. Environment variable names read from config [skills.github-triage].
env:
  - GITHUB_TOKEN


# Optional. Model alias override for this skill only.
model: haiku


# Optional. Iteration limit for this skill (default: 10).
max_iterations: 10
---


## Instructions


When asked to triage issues:


1. Fetch issues from GitHub API.
2. Summarize priority, owner, and next action.
3. Return a concise markdown report.


## Notes


- Prefer open issues unless asked otherwise.
- Flag blocked items explicitly.

Install And Manage External Skills

Use this when you want shared/community skill packs:

Terminal window
# Add a source from GitHub
ash skill add anthropic/skills


# Add a pinned version
ash skill add anthropic/skills@v1.0.0


# Add from a local path
ash skill add ~/my-local-skills


# See configured sources
ash skill sources


# Sync latest from configured sources
ash skill sync


# Update installed repos to latest refs
ash skill update


# Remove a configured source
ash skill remove anthropic/skills

Configure Skills

Global skill behavior in config.toml:

[skills]
auto_sync = true             # Optional bool. Default: false.
update_interval_minutes = 5  # Optional int. Default: 5.

External source declarations:

[[skills.sources]]
repo = "anthropic/skills"      # owner/repo source


[[skills.sources]]
repo = "company/internal-skills"
ref = "v2.0.0"                 # optional branch/tag/commit pin


[[skills.sources]]
path = "~/my-local-skills"     # local source path
# Set exactly one of: repo or path.

Per-skill overrides:

[skills.github-triage]
enabled = true                  # Optional bool. Default: true.
model = "haiku"                 # Optional model override.
GITHUB_TOKEN = "ghp_..."        # Unknown keys become env vars.
MAX_RESULTS = "25"              # Also exposed as env var.

Global and per-skill chat allowlists:

[skills.defaults]
allow_chat_ids = ["12345"]      # Optional global default allowlist


[skills.github-triage]
allow_chat_ids = ["12345"]      # Optional per-skill override

Capability-Backed Skills (Sensitive Integrations)

For email/calendar and similar sensitive systems, skills should call ash-sb capability and declare required capability IDs in frontmatter:

---
description: Manage inbox and calendar through host-managed capabilities
sensitive: true
access:
  chat_types:
    - private
capabilities:
  - gog.email
  - gog.calendar
allowed_tools:
  - bash
---

Provider runtime wiring is host-owned configuration, not skill metadata:

[skills.gog]
enabled = true


[skills.gog.capability_provider]
enabled = true
namespace = "gog"
command = ["gogcli", "bridge"]
timeout_seconds = 30

Bundled Optional gog Skill

Ash includes an opt-in bundled gog skill for dogfooding this contract.

Enable it in config.toml:

[skills.gog] enabled = true

[skills.gog.capability_provider] enabled = true namespace = “gog” command = [“gogcli”, “bridge”] timeout_seconds = 30

When `skills.gog.enabled = true`, Ash auto-wires default
`capabilities.providers.gog` settings unless overridden explicitly.


## Troubleshooting


### Skill does not appear


```bash
# Confirm Ash can discover it
ash skill list --source


# Validate the file directly
ash skill validate ~/.ash/workspace/skills/my-skill/SKILL.md

Skill is present but inactive

[skills.my-skill]
enabled = true

External source is stale or missing updates

Terminal window
ash skill sources
ash skill sync
ash skill update

Repo source fails with git errors

Install git for your platform and retry:

Terminal window
# Ubuntu/Debian
apt install git


# macOS
brew install git

Reference (Advanced)

Storage layout under ~/.ash/:

~/.ash/
├── config.toml
├── skills/                    # User skills
├── skills.installed/          # External skill sources
│   ├── .sources.json
│   ├── .sync_state.json
│   ├── github/
│   └── local/
└── workspace/
    └── skills/                # Project/workspace skills

Internally, discovery is handled by src/ash/skills/registry.py and source metadata tracks built-in, integration, installed, user, and workspace origins.

Compatibility:

  • Agent Skills spec
  • Vercel/Anthropic-style skill repos
  • skild.sh-compatible directory structures