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

# Fly agent skills

> Install the Fly.io agent skills into Claude Code, Codex, Cursor, and other coding agents with fly skills install, then update, pin, or remove them.

The Fly agent skills help coding agents deploy and manage apps on Fly.io. Install them once, and your agent gets instructions for working with Fly Machines, networking, storage, databases, and the `fly` CLI.

A skill is a folder of Markdown instructions in the [Agent Skills](https://agentskills.io) format that an agent loads when a task calls for it. Fly publishes two in [superfly/skills](https://github.com/superfly/skills):

* **`fly`** covers signing in, `fly launch` and `fly deploy`, `fly.toml`, scaling Machines across regions, volumes, secrets, networking, Managed Postgres, Tigris object storage, logs and troubleshooting, and Sprites. It routes the agent to flyctl first and to the Fly MCP server when the client has it connected.
* **`brand`** covers the Fly.io logo, colors, type, and voice for anything that should look or sound like Fly.io.

> [!TIP]
>
> [`fly setup agent`](./setup-agent) installs these skills and adds the hosted Fly MCP server to your agents in one step. Use the `fly skills` commands on this page to install the skills on their own, or to update, pin, or remove them later.

> [!NOTE]
>
> `fly skills` is available in flyctl v0.5.1 and later. If your `fly` does not have the command, run `fly version upgrade` or [install flyctl](https://docs.fly.io/flyctl/install.md).

## Install with flyctl

```sh theme={null}
fly skills install
```

The command downloads the current skills from GitHub and writes them into `~/.agents/skills`, which many agents read, plus the global skills directory of every coding agent it detects on your computer. It lists the directories it is about to write and asks once before it does. Pass `--yes` to skip the prompt, for example in a setup script.

Restart your coding agent after installing. Most agents read their skills directory at startup.

### Supported agents

An agent is detected when its parent directory exists, for example `~/.claude`. To choose agents yourself, name them with `--agent`. Only the agents you name are written, so include `universal` to keep `~/.agents/skills`:

```sh theme={null}
fly skills install --agent universal,claude-code,codex
```

| Agent | Slug | Directory |
| - | - | - |
| Any agent that reads the universal location | `universal` | `~/.agents/skills` |
| Claude Code | `claude-code` | `~/.claude/skills` |
| OpenAI Codex | `codex` | `~/.codex/skills` |
| Cursor | `cursor` | `~/.cursor/skills` |
| OpenCode | `opencode` | `~/.config/opencode/skills` |
| GitHub Copilot | `copilot` | `~/.copilot/skills` |
| Factory Droid | `factory-droid` | `~/.factory/skills` |
| Pi | `pi` | `~/.pi/agent/skills` |
| Antigravity | `antigravity` | `~/.gemini/config/skills` |

## Check and update

`fly skills` on its own, or `fly skills status`, shows the revision installed for each agent, any files you have changed since, and whether a newer revision is available. Add `--json` for JSON output or `--offline` to skip the upstream check.

```sh theme={null}
fly skills update
```

`fly skills update` downloads the latest skills and replaces files you haven't changed. If you've edited a file, the command leaves it alone and reports the change. Use `--force` to overwrite your edits. Only agents that already have the skills installed are updated unless you pass `--agent`.

## Remove

```sh theme={null}
fly skills remove
```

Remove deletes the files that `fly skills install` wrote, including any you've edited, then any directories that became empty. Files you added inside a skill directory are left alone.

## Pin a revision

By default the commands track the `main` branch of superfly/skills. To stay on a known revision, pass a tag or commit SHA:

```sh theme={null}
fly skills install --ref 5fb7159131eba50ba894ccc2bd933a4fa6e47d3c
```

In flyctl releases after v0.5.1, flyctl remembers the pinned version. Later runs of `fly skills update` and `fly skills status` will use the pinned revision. Any status reports will update only when that revision moves. To track `main` again, pass `--ref main` once.

With v0.5.1, pass `--ref` on every update to stay pinned. An update without `--ref` returns to `main`. Status check to look for updates will check against `main`.

## How downloads are verified

`flyctl` resolves the requested revision through the GitHub API and downloads the archive over HTTPS. It checks the archive structure before installing the skills.

`flyctl` also records hashes of the installed files. When you run `fly skills update`, it uses those hashes to identify files you've modified locally so it can preserve your changes.

There is no separate cryptographic signature. Trust rests on TLS to `github.com` and write access to the `superfly/skills` repository, as it does with `flyctl`'s own install script.

## Other ways to install

Any agent that supports the Agent Skills format can install straight from the repository with the [skills CLI](https://skills.sh):

```sh theme={null}
npx skills add superfly/skills
```

Claude Code users can install the skills as a plugin from the repository's marketplace. The repository also ships plugins for Codex, Cursor, Grok Build, and Antigravity; the [README](https://github.com/superfly/skills#plugins-and-marketplaces) has the install steps for each.

```text theme={null}
/plugin marketplace add superfly/skills
/plugin install fly@fly-skills
```

The plugin adds two things the plain skill install does not. It configures the hosted Fly MCP server at `https://mcp.fly.io`, which signs in with browser OAuth and grants access per organization, app, and product. It also installs a confirmation hook that asks before destructive or billable `fly` and `sprite` commands and MCP tools, such as destroying an app or creating a volume. The hook runs with Python 3. If `python3` is missing from `PATH` or is present but cannot run, the hook skips inspection and emits a warning. Your agent's normal permissions still apply. A missing guard script or an unexpected guard error still blocks the command or tool call. With a skills-only install, your agent's normal permission prompts apply instead. The skill also asks the agent to confirm before destructive operations, but only the hook or your client's prompts enforce that.

## How the skills guide an agent

The `fly` skill is written for agents that act on your behalf, so most of it is about method rather than commands. It asks the agent to:

* Check who is signed in and read the current state with commands such as `fly status`, `fly machine list`, and `fly logs` before changing anything.
* Pass the app name explicitly rather than trusting a `fly.toml` in the working directory, and identify the exact app, Machine, or volume from a listing before acting on it.
* Explain the effect of a destructive, disruptive, or billable change and ask before running it, then verify the result afterwards.
* Treat secret values as write-only and never repeat them in output or summaries.
* Load detailed references only when a task needs them, so instructions for `fly.toml`, scaling, Postgres, or Sprites do not crowd out your own project context.

These are instructions, not guarantees. An agent can still misread a situation, so keep your client's permission prompts on for destructive commands and review what it proposes.

The skill text is open source. Suggest changes or report mistakes in [superfly/skills](https://github.com/superfly/skills).