Installing a Skill

What gets installed

aileron skill install <source> fetches the skill, parses its SKILL.md, resolves any declared action requirements against your running daemon, and writes the skill into ~/.aileron/skills/<name>/. The store is the single host-side writer. An installed skill is read-only after install; editing is an explicit future operation.

The install never touches credential values. A skill’s trust contract declares the credential kind and placement only. The resolver matches action references against the actions you already have installed by name; the credential itself is injected at the network boundary at run time, never handed to skill code.

Installing from a local path

aileron skill install ./my-skills/weekly-digest

The source may point at a directory that contains a SKILL.md, or directly at a SKILL.md file. The CLI parses it, resolves its requirements, copies the whole skill folder (SKILL.md plus any reference files) into the store, and prints where it landed:

Installed skill "weekly-metrics-digest" to /Users/you/.aileron/skills/weekly-metrics-digest

Installing from a git URL

aileron skill install https://github.com/acme/weekly-digest.git

Aileron shallow-clones the repository, reads the SKILL.md at its root, and installs it the same way as a local path.

A git-URL install requires the git binary on your PATH. aileron skill install runs host-side, so it is unrestricted by the sandbox egress boundary. If git is missing the install fails with the underlying clone error.

Installing from an OCI reference

aileron skill install ghcr.io/acme/weekly-digest:v1a2b3c4d5e6f

An OCI reference installs a Flight Plan that someone published with aileron skill publish. The reference has a registry host, a repository path, and a version tag. Aileron pulls the signed artifact (the frozen SKILL.md, its lockfile, the signature, and the author public key) from the registry over your existing Docker credentials.

The version tag is optional. Omit it and Aileron installs the latest tag, which aileron skill publish always points at the newest published artifact:

aileron skill install ghcr.io/acme/weekly-digest

The 16-hex content-hash slug (for example v1a2b3c4d5e6f) is the canonical immutable coordinate. latest and any semver label the author froze with aileron skill freeze --version are mutable pointers that move as the author republishes. Whichever tag you install by, Aileron reads the content-hash slug from the artifact and keys the on-disk version off it, so an install by latest and an install by the matching content-hash tag land in the same directory and later launch identically. Pin the content-hash tag when you need a coordinate that never moves.

The install verifies the artifact before anything lands on disk. It checks the author signature and the content hash, then the publisher-trust gate against your keyring, the same checks aileron skill launch runs. A tampered artifact fails the signature check. A plan from a publisher you have not trusted fails the trust gate. Either failure aborts the install and writes nothing to the store. A plan that declares no publisher installs on a valid signature alone.

An OCI install writes a frozen version, so it appears under ~/.aileron/skills/<name>/versions/<id>/ and prints the version it installed:

Installed frozen version v1a2b3c4d5e6f of skill "weekly-metrics-digest" to /Users/you/.aileron/skills/weekly-metrics-digest/versions/v1a2b3c4d5e6f
Bind "weekly-metrics-digest"'s declared credentials now? [Y/n]:

A frozen plan carries a signed trust contract, so the install can derive its credential requirements right away. When you run the install at a terminal, it offers to bind those credentials on the spot. Answering yes (the default) chains straight into aileron skill bind for the version it just wrote, so you onboard the plan’s credentials in one step. Answering no prints the pointer instead:

Run `aileron skill bind "weekly-metrics-digest"` to supply this plan's credentials

The offer only appears at an interactive terminal. A non-interactive install (in CI, or with piped stdin) never blocks on the prompt and always prints the pointer, so a scripted install behaves exactly as before.

The version id is the frozen content-hash slug, so a re-install of the same published plan is a no-op that reuses the same directory. Install does not pull the plan’s container image. The image pin recorded in the lockfile is resolved at aileron skill launch, not at install.

Installing by an agentskills.io ↗ registry slug is not supported. agentskills.io is a format spec, not a registry, so a slug has no canonical location to resolve against. Install from a local path, a git URL, or an OCI reference instead.

Onboarding credentials

A published Flight Plan declares the credentials it needs in its frozen trust contracts, but it never carries the secrets. After you install a frozen plan, run aileron skill bind <name> to supply them:

aileron skill bind weekly-metrics-digest

The verb derives the plan’s credential requirements from its verified frozen trust contracts, then fills only the gaps. For each requirement it checks two places: your vault for the secret, and ~/.aileron/binding-descriptors.yaml for the non-secret binding. A requirement already present in both is reported as satisfied and left untouched. A missing requirement prompts you for its secret with a hidden prompt that writes straight to the vault, prompts for any non-secret parameter such as an AWS access key ID, and writes the binding descriptor entry.

The write is programmatic, so you do not hand-edit any file. A single run stores the vault secret, writes the descriptor entry, prints a per-requirement summary, and reminds you to restart the daemon. The daemon reads binding descriptors once at startup, so a new binding takes effect only after a restart.

The same verb onboards a second operator on their own machine. They install the same frozen plan, run aileron skill bind <name>, and supply their own identity and key. The plan is shared once; each operator binds their own credentials against it. A requirement whose host carries an unresolved input template is surfaced as an advisory rather than written automatically, since the concrete host is not known until launch resolves the input.

For an aws-sigv4 credential the access key ID and the secret are a matched pair. When you re-run bind and the vault already holds the secret, bind fills only the missing access key ID and does not re-prompt for the secret. If you rotated the key (minted a new access key ID and secret, then deleted the old one) and entered the new ID, the vault still holds the old secret, which fails at launch with an opaque SignatureDoesNotMatch. To catch this before launch, bind prints an advisory whenever it writes an access key ID while reusing an existing secret, telling you to run aileron vault put user/<service> with the new secret if you rotated the key so the stored secret matches the entered access key ID.

Action requirements and graceful degrade

When a skill declares requires: action references (for example aileron:metrics.query_series), the installer asks your running daemon which actions are installed and checks each reference. A reference is satisfied when an installed action matches both the connector and the action name.

Install is degrade-not-block. If a reference does not resolve, the install still succeeds and prints a warning naming the unsatisfied references:

warning: skill "weekly-metrics-digest" installed, but 1 action requirement(s) are not satisfiable here:
  - aileron:metrics.query_series
  Install the connectors/actions these refs name, or launch where they are available.

An instruction-only skill (no aileron block) skips requirement resolution entirely, so it installs cleanly and silently even when the daemon is not running.

Listing installed skills

aileron skill list

prints the installed skill names, one per line. When the store is empty it tells you so and points at aileron skill install.

Launch-anywhere projection

You install a skill once. At aileron launch <agent> in the sandbox, the launcher bind-mounts the canonical skill store read-only at the agent’s skills path (for example /home/agent/.claude/skills for Claude Code), so the skill is visible to the agent without copying it per agent. The agent’s MCP configuration already points at the Aileron MCP server, so a skill’s requires: action references resolve through Aileron and stay gated by your approval policy.

Per-agent path differences are absorbed by the launcher, not by rewriting the skill. The mount is read-only: editing an installed skill is an explicit operation, not a side effect of launch.