Amp Replaces Custom Commands with Skills — Migration Guide

Amp is deprecating custom commands in favor of skills; full details are available in the announcement at https://ampcode.com/news/slashing-custom-commands. The change consolidates two overlapping mechanisms—custom commands and skills—into a single model now that users can invoke skills directly. The migration can be performed automatically with an Amp prompt or carried out manually; both approaches are documented below.

Why this change matters

Custom commands and skills provided the same core capability, but with different invocation scopes: historically only the user could invoke custom commands, while only the agent could invoke skills. With user-invokable skills, that distinction no longer applies, so the tooling is being simplified by removing custom commands.

Migration options

Projects with existing custom commands in .agents/commands/ or ~/.config/amp/commands/ have two straightforward migration paths.

Let Amp migrate commands

Amp can handle the migration. Use the following migration prompt with Amp to convert existing commands into skills:

Migrate my custom commands from .agents/commands/ to skills in .agents/skills.

For each command:

1. Create a new skill directory in .agents/skills/ named after the command
2. If it's a markdown file, rename it to SKILL.md and add frontmatter with name and description
3. If it's an executable, create a SKILL.md that describes when and how to run the script, and move the executable to a scripts/ subdirectory
4. Delete the original command file

Also do this for global custom commands in ~/.config/amp/commands (which should be migrated to skills ~/.config/agents/skills).

This preserves existing content while reorganizing it under the .agents/skills/ convention and converting global commands from ~/.config/amp/commands/ to ~/.config/agents/skills/.

Manual migration steps

For teams preferring hands-on control, the manual process is simple and brief.

• Markdown commands: move the .md file into a skill directory and rename it to SKILL.md.
  Example:

  • Before: .agents/commands/code-review.md
  • After: .agents/skills/code-review/SKILL.md
    Add frontmatter at the top of SKILL.md:

  ---

  name: code-review
  description: Review code for quality and best practices

  Then include the existing content below the frontmatter.

• Executable commands: move the executable into a scripts/ subdirectory inside a new skill folder, and include a SKILL.md that documents usage.
  Example layout:

  • Before: .agents/commands/deploy
  • After:
    • .agents/skills/deploy/SKILL.md
    • .agents/skills/deploy/scripts/deploy
      The SKILL.md should include frontmatter:

  ---

  name: deploy
  description: Deploy the application

  and a short instruction such as: Run {baseDir}/scripts/deploy to deploy.

What to expect

After migration, all previously custom command functionality will live under .agents/skills/ (and ~/.config/agents/skills/ for global items), with markdown-based skills using SKILL.md frontmatter for metadata and executables moved into a scripts/ subtree with usage instructions. This aligns repository layout and agent behavior around a single, unified skill model (skills).

For full reference and the original announcement, see: https://ampcode.com/news/slashing-custom-commands