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.

PlaceCommandWritesSaved in
Project, AGENTS.md (default)npx @astryxdesign/cli initThe Astryx block in AGENTS.md, a copy in the Claude Code file the project already has, and an import in GEMINI.mdNothing: it is the default
Project, skills foldernpx @astryxdesign/cli init --to skills.agents/skills/astryx-project/SKILL.md and a copy in .claude/skills/astryx-projectskills.to in astryx.config
This computernpx @astryxdesign/cli init --to user~/.agents/skills/astryx/SKILL.md, linked where other agents lookThe settings file
Any foldernpx @astryxdesign/cli init --to ./team-skills<folder>/astryx-project/SKILL.md in the project; a folder outside it gets the computer skillastryx.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.

bash
npx @astryxdesign/cli init --to skills # move the project to the skills folders
npx @astryxdesign/cli init --to agents-md # move it back; the skill files go
npx @astryxdesign/cli init --to ./bundle --once # a copy that nothing keeps current
npx @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.