Skip to main content
A skill is a reusable instruction bundle the agent can load while working on a task. Each skill is a directory containing a SKILL.md manifest plus any supporting files. Skills come from two places: user skills you upload to your account, and repo skills indexed automatically from a project’s GitHub repository.

​
Authoring a Skill

A skill is a folder whose root contains a SKILL.md file with YAML frontmatter. The frontmatter must include name and description, and name must match the skill’s slug.
SKILL.md
A slug is 1–64 characters, lowercase alphanumeric or dashes, starting and ending with an alphanumeric (e.g. run-migrations). The slug is the skill’s identity — for user skills it defaults to the folder name; for repo skills it’s the directory name under .agents/skills/.

​
Bundle limits

When you upload a skill, Aether enforces: Files must be valid UTF-8 text. Common build and dependency directories — .git, node_modules, dist, build, .next, .cache, target, __pycache__, .venv — are rejected if present, so keep the skill folder to its content.

​
User Skills (CLI)

Manage your saved skills with aether skill (aliased as aether skills).

​
Upload one skill

push uploads a local folder as a user skill. The slug defaults to the folder’s basename; override it with --slug.
If a skill with that slug already exists, the CLI prompts before overwriting. Pass --force to skip the prompt.

​
List, show, download, delete

get --files shows the file list; --out <dir> writes the files to a directory. pull downloads a skill into a directory (pass --force to overwrite a non-empty target). delete prompts for confirmation unless you pass --force.

​
Bulk import

sync discovers skills in well-known local directories and uploads them in one pass:
By default sync scans, in this order:
  • <repo>/.agents/skills
  • <repo>/.claude/skills
  • ~/.claude/skills
  • ~/.codex/skills
It uploads every subdirectory that has a SKILL.md and a valid slug. If the same slug appears in more than one source, the first match wins and later ones are skipped with a warning. Use --dry-run to preview what would be uploaded, --source <dir> to override the search paths (repeatable), and --force to overwrite existing skills without prompting.

​
Repo Skills

When a project’s linked GitHub repository contains skills under .agents/skills/<slug>/SKILL.md, Aether indexes them from the repository’s default branch and offers them to the agent automatically — no upload needed. Update the repo and the indexed skills follow. Repo skills shadow user skills with the same slug: if a repo defines run-migrations and you also have a user skill named run-migrations, the repo version is the one the agent uses for that project. To see the skills effective for a project (repo skills plus your non-shadowed user skills), use the List project skills API.

​
How Skills Reach the Agent

Effective skills are streamed into the workspace under ~/.aether/skills/<slug>/ and symlinked into each agent’s config directory (for example ~/.claude/skills), so the running agent CLI discovers them in its native location. The skills root is wiped and rebuilt on each provision, so deleting a skill removes it from future tasks.

​
API

User skills are also managed over five REST endpoints: Uploaded bundles are validated against the SKILL.md manifest rules above and encrypted at rest.