Where agents read Astryx
In a project, keep the Astryx guidance in AGENTS.md (the default). Add the computer skill so agents outside a project know Astryx is there. `astryx init --to` picks the place and keeps it.Pick a place
In a project, use the AGENTS.md block: every agent reads it, every time. That is what npx @astryxdesign/cli init writes with no options. Use a skills folder only when your team keeps agent guidance as skills. On your computer, add the computer skill so an agent that works outside a project still knows Astryx is there. The project place and the computer place work together: in a project, the project guidance comes first.
| Place | Command | Writes | Saved in |
|---|---|---|---|
| Project, AGENTS.md (default) | npx @astryxdesign/cli init | The Astryx block in AGENTS.md, a copy in the Claude Code file the project already has, and an import in GEMINI.md | Nothing: it is the default |
| Project, skills folder | npx @astryxdesign/cli init --to skills | .agents/skills/astryx-project/SKILL.md and a copy in .claude/skills/astryx-project | skills.to in astryx.config |
| This computer | npx @astryxdesign/cli init --to user | ~/.agents/skills/astryx/SKILL.md, linked where other agents look | The settings file |
| Any folder | npx @astryxdesign/cli init --to ./team-skills | <folder>/astryx-project/SKILL.md in the project; a folder outside it gets the computer skill | astryx.config, or the settings file for a folder outside the project |
Run the commands for this computer and for folders outside a project with the CLI installed for the computer (npm install -g @astryxdesign/cli@latest): it answers them in any folder. In a project, a runner such as npx starts the project's own CLI, and a release from before skill places refuses --to.
A skill loads only when the agent decides the task needs it; the AGENTS.md block is always read. So keep the block when your team uses an agent that reads skills less reliably than AGENTS.md.
Keep each place current
npx @astryxdesign/cli init writes the project's saved places again. npx @astryxdesign/cli upgrade --from <old version> --apply refreshes them after a dependency bump. The CLI installed for the computer writes the computer skill again after each of its upgrades, until npx @astryxdesign/cli init --remove --to user turns it off. It refreshes the folders outside a project you saved while each file is there; after you delete one, npx @astryxdesign/cli init --to <folder> writes it again. npx @astryxdesign/cli doctor checks each place: current, missing, from another release, edited, or there twice.
bashnpx @astryxdesign/cli init --to skills # move the project to the skills foldersnpx @astryxdesign/cli init --to agents-md # move it back; the skill files gonpx @astryxdesign/cli init --to ./bundle --once # a copy that nothing keeps currentnpx @astryxdesign/cli init --remove # remove it from the project's saved places
Moving a project to another place removes the guidance from the old one, so agents never read it twice. A skill file you edited is kept, and so is one Astryx did not write; delete it, then run npx @astryxdesign/cli init (for a folder outside the project, npx @astryxdesign/cli init --to <folder>; for the computer skill, npx @astryxdesign/cli init --to user) to get the current text.