Repository navigation
Conversation
…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>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 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
commented
Nov 16, 2026
djsauble
commented
Nov 16, 2026
djsauble
commented
Nov 16, 2026
…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>
…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>
… 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
floxskill, with onboarding as its referencereferences/agent-stacks.md. It also has "Installing Flox" give the person thesudocommand. Until that PR merges, the reference's URL onmainreturns 404, andmain'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
floxskill and follow its "Installing Flox" section. The agent checks for an existing Flox first. Because the install needssudo, 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 -oand 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:
get.flox.dev, run by the person because it needssudo;flox/flox-agentin a cache environment of its own.Then it runs the onboarding conversation, driving
flox-agent init plan,init decideandinit apply, thenshortcutandsync. 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
claudeandcodexstart 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 onPATH.shortcutchanges nothing and shows how to set one up:flox init -Dorflox 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. Thenshortcutruns again.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,applyandscanare the verbs an agent drives, andinitalone is an interactive onboarding in a terminal.flox agent sync,status,shortcut,overlayandpromoteact 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 withpromote), and the commands the agent ends with, which run through the stack's environment. It says these commands come with onboarding, so aflox-agentwithoutinithas none of them. It also shows how to onboard in a terminal without an agent: make an environment withflox/flox-agentand runflox agent initin it. It warns that the catalog'sflox-agentmay not haveinityet.A fallback for today's
flox-agent. No releasedflox-agenthasinityet. When the skill's check finds none, it makes a simpler stack itself instead of stopping:flox/flox-agent, every agent the person uses, and the catalog's packages of the Claude Code plugins they have enabled, started withflox-agent launch. It finds Claude Code and Codex with--version, and opencode and pi withcommand -v, without running them;claude plugin list --jsonandclaude plugin marketplace list --json, never Claude Code's settings files;Their own skills, other plugins and MCP servers stay where they are. There is no shortcut. Once a
flox-agentrelease hasinit, 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:
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-agentinto an environment, check it withflox agent list, and launch it. It is linked from the guides nav, the quickstart and the overview. The sandbox and skill-repository guides and theflox agent listreference, which sent readers to the quickstart for such an environment, now point at it.llms.txt.headerpoints agents reading the index at thefloxskill for installing Agent Stacks and forflox agent init. Without the skill installed, the agent saves the skill and reads the saved file.llms.txtis 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:floxskill 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..mdfile in this repository becomes a hidden page whose Markdown copy adds a header and a footer and leaves content out.raw.githubusercontent.comserves 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-agentCLI, and the skill neither offers the app nor mentions it.This does not wait for a
flox-agentrelease: with today's, the skill takes the fallback path. Once a release hasinit, 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:Also tell the agent to save
references/agent-stacks.mdfrom the same branch, since the skill namesmain.Checks
valeon the changed pages: 0 errors, 0 warnings, run again after each round of changes.llms.txtmatchesscripts/generate-llms-txt.sh's output.mint broken-links --check-anchorsreports none in them, only problems already onmainelsewhere.flox-agent init --help, run againstflox/flox-agent@0.9.0-413-g31c7241, the buildLATESTnames and the catalog's newest: it printsflox-agent's general usage with noinit, so the skill takes the fallback.flox-agentsetup was run for real in a temporary cache directory:LATESTand pinning the matchingflox/flox-agentversion;flox/flox-agent,agent-stacks/claude-codeand 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 listin that environment, showing the harness and the plugin.🤖 Generated with Claude Code