aggrega skills
Install the Aggrega skill into an AI assistant
Synopsis
aggrega skillsDescription
Install the skill that teaches an AI assistant to install and use Aggrega.
A skill is a folder holding a SKILL.md file in the open Agent Skills format,which many assistants read from a skill folder of their own. The Aggrega skilltells an assistant how to install Aggrega, how to connect it to the aggrega MCPserver, how to start a workspace, and how to run the authoring loop — scaffold,validate, build. It carries no copy of any schema: it sends the assistant tothis binary for every structural question and to the published documentationfor every conceptual one.
The skill is built into this binary, so the copy it installs matches theversion you have.Subcommands
| Command | Description |
|---|---|
aggrega skills install | Write the Aggrega skill into an AI assistant’s skill folder |
aggrega skills list | List the skills this binary ships and the assistants it can install them for |
aggrega skills install description
Write the Aggrega skill into the skill folder of each assistant named with--agent, so the assistant knows how to install and use Aggrega.
By default the skill goes into the assistant's project skill folder at the rootof your workspace — the one found from the directory you run the command in, ornamed with --workspace-root; a directory no workspace marks is its own root —which is where a project's own skills are committed. With --global it goesinto the assistant's per-user skill folder in your home directory instead,where the assistant reads it in every project.
Every folder and file a project installation writes is held to the workspace:a skill folder reached through a link leading out of it is refused, andnothing is written.
--agent may be given more than once. Where several of the named assistants readthe same folder, the skill is written there once.
With --global and no --agent, the skill is installed for the assistants foundon this machine: each one whose configuration folder is in your home directoryor whose command is on your PATH, as the table below names them. The commandprints each assistant it found and what found it. At a terminal it then asksbefore writing: press Enter to install for those, or type the identifiers ofother assistants to add them. Where standard input is not a terminal itinstalls for the assistants found without asking. Where it finds none and isgiven none, it writes nothing and says so. A project installation is for theassistants a project's people use rather than those on one machine, so italways names them with --agent.
The skill is written as a folder named aggrega holding SKILL.md, and every filewritten carries a comment line saying where it comes from. Running the commandagain replaces a copy carrying that line, which is how a newer aggrega bringsthe skill up to its own version. A file at the target that does not carry itwas not written by this command, so the command refuses, names the file andwrites nothing; move it aside or remove it, then run the command again. Everytarget is checked before anything is written, so a refusal leaves every folderas it was.
The assistants it installs for, the folders each one reads, and what finds eachon this machine — its configuration folder in your home directory, or itscommand on your PATH:
--agent assistant project folder per-user folder found by amp Amp .agents/skills ~/.config/amp/skills ~/.config/amp, amp antigravity Antigravity .agents/skills ~/.gemini/config/skills ~/.gemini/antigravity, antigravity antigravity-cli Antigravity CLI .agents/skills ~/.gemini/antigravity-cli/skills ~/.gemini/antigravity-cli claude-code Claude Code .claude/skills ~/.claude/skills ~/.claude, claude cline Cline .cline/skills ~/.cline/skills ~/.cline, cline codex Codex .agents/skills ~/.agents/skills ~/.codex, codex cursor Cursor .cursor/skills ~/.cursor/skills ~/.cursor, cursor gemini-cli Gemini CLI .gemini/skills ~/.gemini/skills gemini github-copilot GitHub Copilot .github/skills ~/.copilot/skills ~/.copilot, copilot goose Goose .agents/skills ~/.agents/skills ~/.config/goose, goose opencode OpenCode .opencode/skills ~/.config/opencode/skills ~/.config/opencode, opencode windsurf Windsurf .devin/skills ~/.codeium/windsurf/skills ~/.codeium/windsurf, windsurf zed Zed .agents/skills ~/.agents/skills ~/.config/zed, zed
An assistant that is not listed is refused by name. It can still use Aggregathrough its MCP server: connect it to "aggrega mcp" ashttps://aggrega.ai/docs/install/ describes.aggrega skills install flags
| Flag | Default | Description |
|---|---|---|
--agent | [] | Assistant to install the skill for, by identifier (for example claude-code, codex, cursor or gemini-cli). Repeatable; the help lists every identifier and the folder each one writes. Required without —global; with —global and none given, the skill is installed for the assistants found on this machine. |
--global | false | Install into each assistant’s per-user skill folder in your home directory, which it reads in every project, instead of the project skill folder at the root of your workspace. |
aggrega skills list description
List the skills built into this binary, and the assistants "aggrega skillsinstall" can write them for, with the project folder and the per-user foldereach assistant reads skills from. It writes nothing.What it does
aggrega skills install writes the Aggrega skill into the skill folder of each AI assistant you name with --agent, or, with --global and no --agent, of each one it finds on this machine. A skill is a folder holding a SKILL.md file in the open Agent Skills format: a short frontmatter block naming the skill and saying when to use it, followed by instructions. An assistant that reads skills loads it when your request matches, so it knows how to install Aggrega, how to connect to aggrega mcp, how to start a workspace, and how to run the authoring loop described in Authoring Aggrega files.
The skill carries no copy of any schema or entity contract. It tells the assistant to ask the binary for every structural answer — the MCP tools where the server is connected, the aggrega command line otherwise — and to read the published documentation for what things mean. The skill is built into the binary, so the copy it writes matches the version you have installed.
aggrega skills install --agent claude-codeInstalled the aggrega skill for Claude Code at /home/you/project/.claude/skills/aggregaWhere the skill lands
Without --global, the skill goes into the assistant’s project skill folder at the root of your workspace, where the assistant looks for the project’s skills and where you commit them. The workspace is the one every command finds — the one --workspace-root names, or the one found from the directory you run the command in, so running it from a sub-folder still installs at the root — and a directory no workspace marks is its own root. With --global, it goes into the assistant’s per-user skill folder in your home directory, which the assistant reads in every project. The table in the description above gives both folders for every assistant; each is the folder that assistant’s own documentation names, and ~ stands for your home directory.
Several assistants read the shared .agents/skills folder. Naming more than one of them writes the skill there once and names them all in the one line that reports it:
aggrega skills install --agent codex --agent zed --globalInstalled the aggrega skill for Codex and Zed at /home/you/.agents/skills/aggregaThe assistants on this machine
With --global and no --agent, the command installs the skill for the assistants it finds on this machine. An assistant counts as found when its own configuration folder is in your home directory, or its command is on your PATH; the found by column of the table in the description above names both for every assistant. A folder or command is used only where it belongs to that assistant alone, so finding it never stands for another one: the shared .agents/skills folder finds nobody, and .gemini, where Gemini CLI and Antigravity both keep files, finds neither — Gemini CLI is found by its gemini command, and each Antigravity product by its own folder beneath .gemini. An assistant whose configuration lives elsewhere on your system is found by its command, or named with --agent.
The command prints each assistant it found and what found it, then installs:
aggrega skills install --globalFound Claude Code (claude-code), from the folder /home/you/.claudeFound Codex (codex), from the command /usr/local/bin/codexInstalled the aggrega skill for Claude Code at /home/you/.claude/skills/aggregaInstalled the aggrega skill for Codex at /home/you/.agents/skills/aggregaAt a terminal it asks first. After the lines naming what it found, it asks you to confirm: press Enter to install for those, or type the identifiers of other assistants, separated by spaces or commas, to add them. Where it found none, it asks for the identifiers instead, and an empty answer writes nothing. Where standard input is not a terminal — a script, an assistant running the command for you, or the assistant’s own tool for it — it asks nothing and installs for the assistants it found. Where it finds none and is given none, it writes nothing, says so, and exits non-zero.
Naming any --agent skips the search: the command installs for the assistants you named and no others. A project installation, without --global, always names them: it is for the assistants the project’s people use, which this machine does not tell.
Installing again, and what it refuses
Every file the command writes carries one comment line, just after the frontmatter, saying that it comes from the skill built into the aggrega binary and that installing again replaces it. That line is how the command tells its own copy from yours:
- A copy carrying the line is replaced. Running the command again after upgrading Aggrega brings the skill up to the new version, and the line it prints says
Replacedrather thanInstalled. - A file without the line is refused. A
SKILL.mdalready at the target that the command did not write is yours, so the command names its path, writes nothing anywhere, and exits non-zero. Move the file aside or remove it, then run the command again. To keep changes of your own, keep them in a skill with another name. - A folder reached through a link leading out of the workspace is refused. Without
--global, every folder and file the command would write is held to the workspace: where an assistant’s skill folder, or a folder on the way to it, is a link leading out of the workspace, the command names the link and where it leads, writes nothing anywhere, and exits non-zero — the condition described in A path the operation writes leads through a link out of the directory it must stay inside. A link that stays inside the workspace is written through.
Every target is checked before anything is written, so a refusal for one assistant leaves every other assistant’s folder as it was too. Files in the skill’s folder that the skill does not write are left alone.
Assistants it does not know
--agent takes only the identifiers in the table above, each one the identifier the open skills command-line tool uses for the same assistant. Any other identifier is refused by name, with the list of the ones it knows. An assistant that is not listed can still use Aggrega: connect it to the MCP server as Connect the MCP server describes, and it reaches the same tools and reference material the skill points to.
Examples
Install the skill for Claude Code in this project:
aggrega skills install --agent claude-codeInstall it for Gemini CLI and Cursor in every project of yours:
aggrega skills install --agent gemini-cli --agent cursor --globalInstall it in every project of yours for the assistants on this machine:
aggrega skills install --globalBring an installed copy up to the binary you have just upgraded to:
aggrega skills install --agent claude-codeListing what it knows
aggrega skills list prints the skills built into this binary with their descriptions, then every assistant aggrega skills install knows, with its project folder and its per-user folder. It writes nothing.
aggrega skills list