> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Author a SKILL.md, upload reusable skills with the CLI, and let repo skills load automatically.

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.

```markdown SKILL.md theme={null}
---
name: run-migrations
description: How to run and verify database migrations in this project.
---

# Running migrations

1. Apply pending migrations with `just migrate`.
2. Verify the schema with `just db-check`.
...
```

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:

| Limit                   | Value  |
| ----------------------- | ------ |
| Files per skill         | 1000   |
| Total uncompressed size | 50 MiB |
| Per-file size           | 5 MiB  |

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`.

```bash theme={null}
aether skill push ./run-migrations
aether skill push ./my-skill --slug run-migrations
```

If a skill with that slug already exists, the CLI prompts before overwriting. Pass `--force` to skip the prompt.

### List, show, download, delete

```bash theme={null}
aether skill list
aether skill get run-migrations --files
aether skill pull run-migrations ./local-dir
aether skill delete run-migrations
```

`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:

```bash theme={null}
aether skill sync
aether skill sync --dry-run
```

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](/api-reference/v1/skills/get-projects-by-id-skills).

## 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:

* [List project skills](/api-reference/v1/skills/get-projects-by-id-skills)
* [List user skills](/api-reference/v1/skills/get-skills)
* [Upload user skill](/api-reference/v1/skills/post-skills)
* [Get user skill](/api-reference/v1/skills/get-skills-by-slug)
* [Delete user skill](/api-reference/v1/skills/delete-skills-by-slug)

Uploaded bundles are validated against the `SKILL.md` manifest rules above and encrypted at rest.