Skip to main content
A skill is a folder of instructions and supporting files the agent can load to perform a specialized task. Each skill is identified by a slug and described by a SKILL.md manifest. Skills come from two sources — ones you upload to your account, and ones discovered in a project’s GitHub repository — and are materialized into the workspace so the agent can read them.

​
The SKILL.md Manifest

Every skill is a directory containing a SKILL.md file. That file must begin with YAML frontmatter, and the frontmatter must include both a name and a description:
SKILL.md
The contract is strict and validated when you upload or index a skill:
  • name is required and must exactly match the skill’s slug.
  • description is required.
  • The file must start with a --- frontmatter block.
A slug is 1–64 lowercase alphanumeric or dash characters and must start and end with an alphanumeric character.

​
User Skills vs Repo Skills

User skills are saved to your account and available across all your projects. Upload them with the aether skill command family — push a local folder, or sync to bulk-import skills discovered in .agents/skills and .claude/skills (in the current repo) and ~/.claude/skills and ~/.codex/skills (in your home directory). A skill bundle may contain up to 1000 files, with a 5 MB per-file and 50 MB total uncompressed limit. User skills are encrypted at rest. Repo skills are discovered automatically. When a project is linked to a GitHub repository, Aether indexes any .agents/skills/<slug>/SKILL.md files on the repository’s default branch and offers those skills to the agent for that project.

​
Slug Shadowing

A project sees a single, combined skill set. When a repo skill and a user skill share the same slug, the valid repo skill wins — it shadows your user skill of the same slug for that project. This lets a repository pin a project-specific version of a skill without you having to remove your personal one.

​
How Skills Reach the VM

When a workspace is provisioned, your skills are streamed into a canonical skills directory in the VM at ~/.aether/skills/<slug>/. This directory is wiped and rebuilt on each provision, so deleting a skill removes it from the workspace on the next run. The canonical directory is then symlinked into each agent’s own config location (for example ~/.claude/skills), so whichever agent provider you run can read the same set.

Skills Guide

Authoring, uploading, and syncing skills with the CLI.

GitHub Integration

Linking a repo so its skills are indexed.

Skills API

List, upload, and delete skills over the API.

Agents & Models

The agents that consume your skills.