Skip to main content
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 format that an agent loads when a task calls for it. Fly publishes two in 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.
fly 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.
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.

ā€‹
Install with flyctl

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:

ā€‹
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.
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

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:
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:
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 has the install steps for each.
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.