Skills commands

This topic covers the agent skills commands for the Postman CLI.

The postman init command installs a set of agent skills into your project, fetched from the Postman skills repository. Because the CLI writes those files into your repository and you commit them, they can fall behind the latest published version over time. The postman skills commands check for and apply updates in an existing project, without having to re-run postman init.

When you work with an AI agent, the installed SKILL.md instructs the agent to keep the skills current for you. At the start of a session, the agent runs postman skills status, and if the skills are behind, it asks you before running postman skills update to fetch the latest. You can also run these commands yourself, as described here.

postman skills status

This command reports whether the agent skills in your repository are up to date with the latest published version. Run it from the root of a project that has skills installed.

For each skill, the command reports one of these states:

• Current — Matches the latest published version.
• Behind — A newer version of a skill you have is published. Run postman skills update to fetch it.
• Missing — A published skill file that isn’t on disk yet, such as a skill added since you ran postman init. postman skills update installs it.
• Modified — You edited the skill file locally. postman skills update overwrites it only with --force.
• Unknown — A published skill file that’s on disk but that postman init didn’t record installing, so it can’t be compared. postman skills update overwrites it only with --force.

By default, the command exits with code 0 whatever the result, so it’s safe for an AI agent to run at the start of a session. Pass --strict to exit with a non-zero code when the skills aren’t current, which is useful as a CI gate. If the command can’t reach the skills repository, it fails with an error.

Usage

postman skills status [path]

Options

Exit codes

Examples

# Check whether the skills are up to date
postman skills status
# Fail in CI when the skills are behind
postman skills status --strict

postman skills update

This command fetches the latest agent skills from the Postman skills repository into your repository, without running the rest of postman init. It also installs any skills published since you last ran postman init, not only newer versions of the ones you already have. Use it to bring an existing project up to date after postman skills status reports that skills are behind.

To protect your work, postman skills update won’t overwrite a published skill file it can’t confirm is safe to replace: one you edited locally, or one it has no record of installing (so it can’t rule out an edit). If it finds one or more of these, it reports them and makes no changes. Pass --force to overwrite these files with the published versions. Any local edits are lost.

If your project has a skill that the repository no longer publishes, postman skills update leaves it in place rather than deleting it, even with --force.

The postman skills update command acts only on published skills. Other files you keep in postman/skills/, such as your own notes, are left alone: it never overwrites or deletes them.

Usage

postman skills update [path]

Options

Exit codes

Examples

# Update the skills to the latest published version
postman skills update
# Preview what would change without writing anything
postman skills update --dry-run
# Overwrite skill files that were edited locally
postman skills update --force

Learn more at Native Git workflows.