Skip to content

docs(ai-agents): install Flox and onboard from the agent you already use, with the flox skill - #155

Open
djsauble wants to merge 8 commits into
mainfrom
daniel/agent-stacks-onboard-skill
Open

djsauble wants to merge 8 commits into
mainfrom
daniel/agent-stacks-onboard-skill

Conversation

@djsauble

@djsauble djsauble commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Two pages now offer a prompt to paste into the AI agent you already use, and both prompts use the same skill: flox, from flox/flox-skills. Depending on the page, the agent installs Flox, or installs Flox and Agent Stacks and turns the agent setup you already have into an agent stack.

This PR depends on flox/flox-skills#120 and merges after it. That PR adds "Installing Agent Stacks" to the flox skill, with onboarding as its reference references/agent-stacks.md. It also has "Installing Flox" give the person the sudo command. Until that PR merges, the reference's URL on main returns 404, and main's SKILL.md has no "Installing Agent Stacks".

  • Install Flox (install-flox/install.mdx) gains a short section at the top, "Install with your AI agent". Its prompt has the agent save the flox skill and follow its "Installing Flox" section. The agent checks for an existing Flox first. Because the install needs sudo, it gives the person the command to run in a terminal of their own, and it never asks for a password. The section points to the quickstart for Agent Stacks. The manual instructions follow, unchanged.

  • The AI agent quickstart (ai-agents/quickstart.mdx) has the agent save the same skill and follow its "Installing Agent Stacks" section. That section sends the agent to the Agent Stacks reference, which it follows from start to finish: it installs Flox and Agent Stacks if they are missing, then onboards.

  • Both prompts have the agent save the skill with curl -o and read the saved file with its file tool. A web fetch tool may hand the model a summary, and some agents cut a command's long output short. SKILL.md is over 30 KB, and the skill has to be read whole. The quickstart links to the skill and the reference on GitHub for people who want to read them first.

  • The skill works in any agent with a shell: Claude Code, Codex, or another. It checks the machine and sets up what onboarding needs, asking before each install:

    • the system;
    • Flox 1.18 or later, through get.flox.dev, run by the person because it needs sudo;
    • the FloxHub login, also run by the person;
    • beta features;
    • flox/flox-agent in a cache environment of its own.

    Then it runs the onboarding conversation, driving flox-agent init plan, init decide and init apply, then shortcut and sync. Claude Code asks with AskUserQuestion; other agents ask in the chat with numbered options. Every step that installs something, changes a setting or sends anything off the machine waits for the person's answer.

  • A stack starts every agent the person uses. It brings each of Claude Code, Codex, opencode and pi that the person uses, and Claude Code when there is no sign of any. The one they start most is its main agent. When it brings more than one, the agent names them all before it asks to create the stack, and it ends with a start command for each.

  • The shortcut only adds the stack to the default environment. Its answers name every command it makes start the stack, such as "Make claude and codex start it". It adds the stack to the [include] of the default environment the person's shell activates, and comments out what that environment installs for the same commands while the include stands. Onboarding never writes a startup file or puts a script on PATH.

    • Without a default environment, shortcut changes nothing and shows how to set one up: flox init -D or flox pull -D, and the line the default environment tutorial gives for each shell. That is the person's to do, never the agent's, because it edits their startup file. Then shortcut runs again.
    • A default environment on FloxHub includes the stack only once the stack is on FloxHub too, so for a stack kept on this computer, the quickstart also offers one in the home directory, flox init -d ~, which includes it at once. Until the shortcut takes, the agent's start commands work.
  • The command names follow the CLI's new design. flox agent init (flox-agent init) makes a stack: init plan, decide, apply and scan are the verbs an agent drives, and init alone is an interactive onboarding in a terminal. flox agent sync, status, shortcut, overlay and promote act on the stack afterwards. The quickstart names them so: the engine check (flox-agent init --help), the bootstrap's commands, the undo command, the table of commands for later (now with promote), and the commands the agent ends with, which run through the stack's environment. It says these commands come with onboarding, so a flox-agent without init has none of them. It also shows how to onboard in a terminal without an agent: make an environment with flox/flox-agent and run flox agent init in it. It warns that the catalog's flox-agent may not have init yet.

  • A fallback for today's flox-agent. No released flox-agent has init yet. When the skill's check finds none, it makes a simpler stack itself instead of stopping:

    • a Flox environment holding flox/flox-agent, every agent the person uses, and the catalog's packages of the Claude Code plugins they have enabled, started with flox-agent launch. It finds Claude Code and Codex with --version, and opencode and pi with command -v, without running them;
    • a plugin goes in only when the catalog has a package of the same name made from the same GitHub repository as the person's marketplace, as agent-pkgs records it, because some catalog packages share a name with a different plugin;
    • it reads plugins through claude plugin list --json and claude plugin marketplace list --json, never Claude Code's settings files;
    • it pushes the environment to FloxHub only after "Create it, on all my computers".

    Their own skills, other plugins and MCP servers stay where they are. There is no shortcut. Once a flox-agent release has init, the same prompt takes the full path with no change to this page.

  • The quickstart is now about onboarding the setup you already have, from the agent you already use. Beside the prompt, it covers:

    • each step, and what the agent asks before it;
    • what onboarding reads and writes;
    • what leaves the machine, and with which answer;
    • what the shortcut changes, what to do without a default environment, and how to undo it.
  • A new guide, Onboard your agent setup by hand, holds the manual steps the quickstart had, unchanged: install Claude Code, a plugin and flox/flox-agent into an environment, check it with flox agent list, and launch it. It is linked from the guides nav, the quickstart and the overview. The sandbox and skill-repository guides and the flox agent list reference, which sent readers to the quickstart for such an environment, now point at it.

  • llms.txt.header points agents reading the index at the flox skill for installing Agent Stacks and for flox agent init. Without the skill installed, the agent saves the skill and reads the saved file. llms.txt is regenerated.

Why the skill lives in flox/flox-skills

An earlier version of this PR hosted an onboarding skill of its own under ai-agents/skills/. It is gone:

  • The flox skill already teaches agents to install Flox. With Agent Stacks in the same skill, the install page and the quickstart give one prompt shape for one skill, and agents that have Flox's skills installed get onboarding too.
  • Mintlify does not serve a skill byte for byte: a .md file in this repository becomes a hidden page whose Markdown copy adds a header and a footer and leaves content out. raw.githubusercontent.com serves the file as it is, which an agent following a skill step by step needs.

Before this merges

Flox.app is left out for now: onboarding uses the flox-agent CLI, and the skill neither offers the app nor mentions it.

This does not wait for a flox-agent release: with today's, the skill takes the fallback path. Once a release has init, run the prompt end to end again, on the full path.

Try it before merge

The prompts' URLs point at flox-skills' main. Until flox/flox-skills#120 merges, put the branch's copy of the skill in the prompt:

https://raw.githubusercontent.com/flox/flox-skills/refs/heads/daniel/agent-stacks-install-and-init/flox-plugin/skills/flox/SKILL.md

Also tell the agent to save references/agent-stacks.md from the same branch, since the skill names main.

Checks

  • vale on the changed pages: 0 errors, 0 warnings, run again after each round of changes.
  • llms.txt matches scripts/generate-llms-txt.sh's output.
  • Every internal link and anchor in the changed pages resolves: mint broken-links --check-anchors reports none in them, only problems already on main elsewhere.
  • The engine check, flox-agent init --help, run against flox/flox-agent@0.9.0-413-g31c7241, the build LATEST names and the catalog's newest: it prints flox-agent's general usage with no init, so the skill takes the fallback.
  • Earlier, with the skill hosted here, its flox-agent setup was run for real in a temporary cache directory:
    • reading LATEST and pinning the matching flox/flox-agent version;
    • making the environment and locking it.
  • The fallback's steps, run by hand on a Mac with Apple silicon:
    • the plugin matching, against a real Claude Code setup: it took a plugin whose catalog package comes from the same repository, and left out two whose catalog packages share the name but come from other repositories;
    • the manifest, with flox/flox-agent, agent-stacks/claude-code and a catalog plugin, locked for the three systems. With the packages in one group it does not resolve, so each has its own, as onboarding's own stacks do;
    • flox-agent list in that environment, showing the harness and the plugin.
  • Not run: either prompt as a whole conversation in an agent, and the push to FloxHub.

🤖 Generated with Claude Code

…d skill

A prompt in the quickstart has the person's own agent (Claude Code,
Codex, or another with a shell) download the onboarding skill with curl
and follow it. The skill sets up what onboarding needs, asking before
each install: Flox, the FloxHub login, beta features, Flox.app on
macOS, and flox-agent in a cache environment of its own. Then it runs
the onboarding conversation, driving flox-agent onboard's verbs. So the
person needs nothing installed first.

The skill lives at ai-agents/skills/agent-stacks-onboard/SKILL.md and
is downloaded raw from GitHub. .mintignore keeps Mintlify from
publishing it as a page, whose Markdown copy would not be the file, and
it is not a Mintlify custom skill, which would replace the skill.md
Mintlify generates for the site.

A new guide, Onboard your agent setup, says what each step does, what
onboarding reads and writes, what leaves the machine and with which
answer, and what the shortcut changes and how to undo it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
flox 🟢 Ready View Preview Nov 16, 2026, 8:34 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

The onboarding skill stopped when the flox-agent the catalog serves had
no onboard command. It now makes a simpler stack in that case: a Flox
environment with flox-agent, the person's agent and the catalog's
packages of their Claude Code plugins, started with flox-agent launch.
A plugin is taken only when the catalog's package comes from the same
repository as theirs. The guide describes it, and what it pushes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Flox.app has no public download yet, so the onboarding skill no longer
offers it during setup, and neither the skill nor the guide says the app
lists the stack. Onboarding uses the flox-agent CLI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@djsauble
djsauble marked this pull request as ready for review November 16, 2026 18:34
@djsauble djsauble self-assigned this Nov 16, 2026
Comment thread ai-agents/quickstart.mdx Resolved
Comment thread ai-agents/quickstart.mdx Resolved
Comment thread ai-agents/guides/onboard-your-setup.mdx Resolved
…e steps by hand

The quickstart is now about onboarding the setup you already have: it
holds the prompt and everything the onboarding guide said about what
the agent does, reads, writes and sends.
Onboard your agent setup becomes Onboard your agent setup by hand,
holding the manual steps the quickstart had, unchanged.
The overview and the pages that sent readers to the quickstart for an
environment with flox-agent now point at the manual guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
djsauble and others added 2 commits November 16, 2026 11:42
…x agent init

The onboarding skill moves to flox/flox-skills, into the flox skill:
"Installing Agent Stacks", and onboarding as its reference
references/agent-stacks.md. The skill this branch hosted under
ai-agents/skills/ is removed, with its .mintignore entry.

- Install Flox gains a prompt at the top that has an agent download
  the flox skill and follow its "Installing Flox" section; the manual
  instructions follow, unchanged.
- The quickstart's prompt uses the same skill: install Flox and Agent
  Stacks if they are missing, then onboard through its Agent Stacks
  reference. It links to the skill and the reference on GitHub.
- The quickstart names the commands as the CLI now does: flox agent
  init, whose plan, decide and apply verbs the agent drives, and the
  top-level flox agent sync, status, shortcut, overlay and promote.
  The engine check is flox-agent init --help, the fallback names
  init, and it says init alone onboards in a terminal.
- llms.txt.header points agents at the flox skill for installing
  Agent Stacks and for flox agent init; llms.txt is regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gent init

- Both prompts have the agent save the flox skill with curl and read
  the file with its file tool: the skill is over 30 KB, and some
  agents cut a command's long output short.
- The quickstart's prompt names the skill's "Installing Agent Stacks"
  section and the reference it sends the agent to, not the whole
  skill, which is a general Flox guide.
- Install Flox says the agent checks for an existing Flox first, and
  gives the person the sudo command to run in a terminal of their own,
  as the skill now says.
- Onboarding in a terminal gives the commands that make an environment
  with flox/flox-agent and run `flox agent init` in it, and says the
  catalog's flox-agent may not have `init` yet.
- The table of commands for later lists them bare again, to put after
  either prefix above it, and says they come with onboarding.
- llms.txt.header has an agent save the skill too; llms.txt is
  regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@djsauble djsauble changed the title docs(ai-agents): onboard from the agent you already use, with a hosted skill docs(ai-agents): install Flox and onboard from the agent you already use, with the flox skill Nov 16, 2026
djsauble and others added 2 commits November 16, 2026 12:17
… only includes it

- A stack brings every agent the person uses among Claude Code, Codex,
  opencode and pi, and Claude Code when there is no sign of any. The
  summary names the main one, the agent they start most often.
- The shortcut answers name every command they make start the stack,
  such as "Make claude and codex start it". The shortcut only adds the
  stack to the default environment's [include]; the section on a
  script on PATH, and every startup-file write it made, are gone.
- Without a default environment, the shortcut changes nothing and says
  how to set one up: flox init -D or flox pull -D, and the line the
  default environment tutorial gives for each shell. That is the
  person's to do, never the agent's; then shortcut includes the stack.
- What onboarding writes says it never writes a startup file, and
  undoing the shortcut only takes the include out.
- The simpler stack, made before flox-agent has onboarding, also brings
  every agent whose command runs, with a launch command for each.
- The quickstart's description says agents; llms.txt is regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… stack kept here

- The "Make claude start it" answer says that, for a default
  environment on FloxHub and a stack kept on this computer, the include
  waits until the stack is shared, and how to start the stack meanwhile.
- Without a default environment, a stack kept on this computer can use
  one in the home directory, `flox init -d ~`, which includes it at
  once, as the default environment tutorial shows.
- Onboarding runs `claude --version` and `codex --version` only, and the
  simpler stack finds opencode and pi with `command -v`: opencode
  writes its state even for `--version`.
- When the stack brings more than one agent, the agent names them all
  before it asks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging — bdace2b7 Deployed Nov 16, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant