Skills

Skills are reusable instruction files that extend the agent’s capabilities. Unlike tools (which execute code), skills are instruction sets that the agent reads and follows.

Overview

When a skill is invoked:

1. The agent reads the skill’s instructions (markdown content)
2. The agent follows the instructions using available tools
3. No code execution happens - the agent just follows the steps

This makes skills powerful for complex workflows that combine multiple tools.

Skill Sources

Skills are loaded from multiple sources in order of precedence (later sources override earlier):

Priority	Source	Location	Description
1 (lowest)	Bundled	Built-in	Skills bundled with Ash
2	Installed	~/.ash/skills.installed/	External repos and local paths
3	User	~/.ash/skills/	User-created skills
4 (highest)	Workspace	workspace/skills/	Project-specific skills

This allows workspace skills to override installed skills, and installed skills to override bundled ones.

Skill Formats

Skills can be defined in two formats:

Directory Format (Preferred)

• Directorymy-skill/

  • SKILL.md Required: skill definition
  • Directoryscripts/ Optional: helper scripts

    • …
  • Directoryreferences/ Optional: reference docs

    • …
  • Directoryassets/ Optional: other files

    • …

The skill name comes from the directory name.

Flat File Format

~/.ash/workspace/skills/my-skill.md

The skill name comes from the filename.

Skill Definition

Skills use markdown files with YAML frontmatter:

---
description: What the skill does (required)
authors:
  - Your Name
rationale: Why this skill was created
env:
  - API_KEY
packages:
  - curl
  - jq
tools:
  - bash
  - web_search
model: haiku  # Optional model override
max_iterations: 10
---

## Instructions

Step-by-step instructions the agent will follow...

## Implementation

Details about how to accomplish the task...

Frontmatter Fields

Field	Type	Required	Description
description	string	Yes	One-line description shown to the agent
name	string	No	Override skill name (default: directory/file name)
authors	list	No	Who created/maintains this skill
rationale	string	No	Why this skill was created
env	list	No	Environment variables to inject from config
packages	list	No	System packages required (apt)
tools	list	No	Tools the skill can use (empty = all)
model	string	No	Model alias override for this skill
max_iterations	int	No	Iteration limit (default: 10)

Configuration

Global Settings

[skills]
auto_sync = true       # Sync sources on startup (optional)
update_interval = 24   # Hours between auto-updates (optional)

Setting	Type	Default	Description
auto_sync	bool	false	Automatically sync sources on startup
update_interval	int	24	Hours between automatic updates

External Sources

Add skill sources using [[skills.sources]] array entries:

# GitHub repo
[[skills.sources]]
repo = "anthropic/skills"

# Pinned to version
[[skills.sources]]
repo = "company/internal-skills"
ref = "v2.0.0"

# Local path (symlinked)
[[skills.sources]]
path = "~/my-local-skills"

Field	Type	Description
repo	string	GitHub repo in owner/repo format
path	string	Local filesystem path
ref	string	Git ref (branch, tag, commit) - repos only

Note

Each source must have either repo or path, not both.

Per-Skill Configuration

Configure individual skills with [skills.name] sections:

[skills.research]
enabled = true
PERPLEXITY_API_KEY = "pplx-..."

[skills.code-review]
model = "haiku"
MAX_FILES = "10"

[skills.deprecated-tool]
enabled = false

Field	Type	Description
enabled	bool	Enable/disable the skill (default: true)
model	string	Model alias override for this skill
*	string	Any other field becomes an environment variable

Environment variables are auto-uppercased: ha_token becomes HA_TOKEN.

CLI Commands

Managing Sources

# Add from GitHub
ash skill add anthropic/skills

# Pin to version
ash skill add anthropic/skills@v1.0.0

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

# List configured sources
ash skill sources

# Sync all from config
ash skill sync

# Update repos to latest
ash skill update

# Remove a source
ash skill remove anthropic/skills

Creating Skills

# Create a new skill directory
ash skill init my-skill

# Create with description
ash skill init my-skill -d "Do something useful"

# Create with resource directories
ash skill init my-skill --resources scripts,references

Validating Skills

# Validate a skill file
ash skill validate ~/.ash/workspace/skills/my-skill

# List all available skills
ash skill list

# Show skill sources
ash skill list --source

Directory Structure

After installation, skills are stored in:

~/.ash/
├── config.toml                # Configuration with [[skills.sources]]
├── skills/                    # User skills (manually created)
│   └── my-skill/
│       └── SKILL.md
├── skills.installed/          # External skills (managed by CLI)
│   ├── .sources.json          # Installation metadata
│   ├── github/
│   │   └── anthropic__skills/ # Cloned repos
│   └── local/
│       └── ash-skills -> ~/   # Symlinks
└── workspace/
    └── skills/                # Project-specific skills

Skill Registry

Location: src/ash/skills/registry.py

Skills are discovered from all sources:

registry = SkillRegistry()
registry.discover(workspace_path)

skill = registry.get("my-skill")
available_skills = registry.list_available()

The registry tracks source type for each skill:

skill.source_type  # SkillSourceType.WORKSPACE, INSTALLED, USER, BUNDLED
skill.source_repo  # "owner/repo" if installed from GitHub
skill.source_ref   # Git ref if pinned

Example Skill

---
description: Search and summarize GitHub issues
env:
  - GITHUB_TOKEN
tools:
  - bash
  - web_fetch
---

## Instructions

When asked to find GitHub issues:

1. Use bash to call the GitHub API:
   \`\`\`bash
   curl -s "https://api.github.com/repos/$owner/$repo/issues" \
     -H "Authorization: Bearer $GITHUB_TOKEN"
   \`\`\`

2. Parse the JSON response to extract:
   - Issue number
   - Title
   - State (open/closed)
   - Labels

3. Format as a markdown table

## Notes

- Respect rate limits (5000 requests/hour with auth)
- Filter by state using `?state=open` or `?state=closed`

Troubleshooting

Skill not loading

Check if the skill is enabled:

ash skill list --source

Verify per-skill config:

[skills.my-skill]
enabled = true  # Make sure this isn't false

Source not syncing

Manually sync:

ash skill sync

Check source status:

ash skill sources

Git not found

Install git for repo sources:

# Ubuntu/Debian
apt install git

# macOS
brew install git

Compatibility

The skill format is compatible with:

• Agent Skills spec - Standard skill format
• Vercel/Anthropic skill repos - Works with community skill repos
• skild.sh packages - Structure-compatible

Tip

Skills are instruction-based, not script-based. Write clear steps the agent can follow using its available tools.