Amp native reference
Start with the Amp setup.
Native mappings
Rules
- Root rules go into
AGENTS.md. Scoped rules use<scope>/AGENTS.md. - See directory-specific instructions for how other tools read them.
Skills
Skills use Amp's native layout, with name and description in frontmatter. Bundled files are copied unchanged.
- Amp replaced custom slash commands with skills, so skills are no longer written as
.agents/commands/skill-<name>.md. - Amp has no user-only skill. It removed user-invokable skills on 2026-05-06, and the model decides when to load every skill. So
disable-model-invocationis dropped with a note, and commands are skipped. - Any
x-ampkey passes through. x-amp.mcpServersties MCP servers to one skill and hides their tools until it loads. Amp recommends this over user settings (Amp skills docs). A siblingmcp.jsonalso works; frontmatter wins.- Amp also loads
.claude/skills/,~/.claude/skills/, and~/.claude/plugins/cache/. The first skill with a givennamewins, and.agents/skills/comes before.claude/skills/(skill order). - A skill synced to both
claudeandamploads once. A skill forclaudeonly still loads. - A skill with the same name in
~/.config/agents/skills/,~/.agents/skills/, or~/.config/amp/skills/hides the project skill.~/.claude/skills/does not.
Skill-loading settings (settings schema), set with x-amp on a settings spec. None has a portable field.
| Setting | Effect |
|---|---|
amp.skills.disableClaudeCodeSkills | Skips the Claude Code directories |
amp.skills.disableGlobalAgentsSkills | Skips ~/.config/agents/skills/ and ~/.agents/skills/ |
amp.skills.path | Adds directories, separated by colons or semicolons |
Agents
No native agent output. The default writes no agent file. outputs.amp.agents: skill converts the prompt to a skill.
- Amp removed custom commands, so sync no longer writes
.agents/commands/<name>.mdand removes old ones. - With
outputs.amp.rules-fileset, agent bodies reach Amp in the combined document. Otherwise Amp gets only the entry-point pointer to the source specs, and sync says so. - By default, agents do not go to
.agents/skills/<name>/SKILL.md. Other tools share that tree, so an agent would duplicate the spec and overwrite a skill of the same name. - Amp's native agent API (
amp.createAgent(...),amp.registerAgentMode(...)in plugins) works only in code.
Commands
Not supported.
- Commands register in plugin code via
amp.registerCommand(...)(Amp docs index). - A command spec for amp is skipped with a warning (
on-unsupported: warnby default). .agents/checks/is gone from Amp's docs, so there is no review output either.
MCP
Servers go under amp.mcpServers (one dotted key, not a nested object).
- Stdio writes
command,args,env. HTTP and SSE writeurl,headers. Other fields go throughx-amp. x-amp.includeToolslimits the tools a server exposes (tool names or globs, Amp skills docs). Amp recommends fewer tools for better model performance. It stays underx-ampbecause Amp's MCP page does not mention it.- Sync changes only
amp.mcpServers. Other keys (theme, editor settings) stay. - Workspace MCP servers need approval. The CLI asks when it first finds one, and orbs ask separately.
- An orb approval can cover later orbs, yours or (from a workspace admin) every member's, until a synced change to that server's entry makes orbs ask again.
Settings
Amp does not read portable settings. Each sync reports unsupported permissions.allow, permissions.deny, permissions.ask, and model. Your portable deny list is not enforced. Only x-amp keys, in Amp's spelling, are written.
- Keys go to
.amp/settings.json, Amp's workspace settings file. Amp searches up from the working directory to the repository root. - Workspace settings override user settings, except
amp.keymap: user keymap entries override workspace ones. - MCP servers and settings are merged in one write. Every other key stays.
allowandaskcannot be written. Amp's settings schema has no tool allow-list.amp.tools.disableonly disables, andamp.mcpPermissionsmatches MCP servers, not tools. Amp does not ask for approval by default and points to a permissions plugin.modelhas no key: Amp picks models through its model selector.- Portable
denyis not enforced.amp.tools.disabletakes native tool names,builtin:toolname, and*patterns. Runamp tools list, then copy the names to disable intox-amp.amp.tools.disable. Use names from your installed version: a name Amp does not recognize leaves the tool available. - A settings spec cannot set
amp.mcpServers, because that would replace every server from MCP specs. - The nearest file wins, with no merging. A subdirectory with its own
.amp/hides the root file for that subtree, for settings andamp.mcpServers. Delete the nested.amp/or copy the generated keys into it.
Environments
install writes an executable .agents/setup. Amp runs it while preparing a project orb or snapshot.
- Amp runs it again when it refreshes a snapshot, so make it safe to repeat.
- Amp stops it after 20 minutes, including the time the project's pre-setup script (set in project settings) takes.
- A shared project snapshot keeps only the
PATHdirectories that setup adds through~/.bashrcand the other bash profile files. Put aliases, shell functions, oreval "$(mise activate bash)"in a hand-written.agents/resume. - Sync does not write
.agents/resume. Amp runs it after activation and on every wake with thread credentials, outside dependency setup and services.
Named terminals write .amp/services.yaml: services Amp keeps running, apart from the setup script.
- Each service needs
command. - Its name uses only lowercase letters, numbers, and hyphens, starts with a letter or number, and has at most 32 characters.
x-amp.terminalscan setcwd,port,env,health,portal,portals,review,platforms.platformsis an optional list oflinuxordarwin. Amp skips a service that leaves out its OS. An empty list is invalid.- Environment specs merge by top-level field. The last one wins.
Old AGENT.md files
Amp uses AGENTS.md (plural). On the first sync after upgrading, a generated AGENT.md at the configured root is renamed to AGENT.md.bak. A hand-written AGENT.md (no Generated by agnostic-ai marker) is left alone.
Config keys
| Key | Default | Notes |
|---|---|---|
outputs.amp.skills-dir | .agents/skills | |
outputs.amp.agents | unset (agents are dropped) | skill writes each agent as an on-demand skill. Off, with a note, while another tool with subagents writes the same skills folder; see agents as skills |
outputs.amp.mcp-file | .amp/settings.json | also carries settings; one file, one override |
outputs.amp.setup-file | .agents/setup | |
outputs.amp.environment-file | .amp/services.yaml | |
outputs.amp.rules-file | unset | writes legacy joined rules and skips instructions that point to source specs |
outputs.amp.commands-dir no longer has an effect.
Import
agnostic-ai import amp reads AGENTS.md, skills from .agents/skills/, and MCP servers from .amp/settings.json.
- Skill folders are restored in full, with bundled files and executable modes.
- Settings keys are not imported, because none has a portable field.
- An old
.agents/commands/tree still imports, one agent per file.