Agent Skill CLI

This is the CLI's own Agent Skill: the procedure an agent reads to drive ai-stp. It is not a component of kind skill inside a setup. Those are skill components. Mixing the two is how an agent overwrites a user's workflow file, or skips installing the control-plane skill because a catalog card exists.

The Skill is what an agent reads to learn how to drive this CLI, so an installation that carries the binary and not the procedure has delivered half a product. After it is present, the agent still starts every session with task intents --json.

The destination is named rather than discovered. Where each harness looks for a native skill is a fact about that harness. This command group will not search the disk for a likely folder. If you do not know the directory, ask the harness documentation, not this CLI.

Commands

Command	Mutability	Confirmation	When
ai-stp skill install	apply	none	Install the canonical Agent Skill at a named destination.
ai-stp skill status	read	none	Report what Agent Skill is at a destination and who owns it.
ai-stp skill remove	apply	none	Remove the Agent Skill this installation put at a destination.

--target is required on all three. It is the directory the harness reads its native skill from. There is no configured fallback. The CLI does not guess the harness's skill directory.

remove is apply, not destructive. It takes back the package this installation wrote. It does not discard identity or the local registry.

Typical path

ai-stp skill status --target <dir> --json
ai-stp skill install --target <dir> --json
ai-stp skill status --target <dir> --json

<dir> is the directory the harness reads its native skill from, not a project root and not the managed toolchain directory. Exact layout is a fact about that harness. Inventing those paths would be a guess presented as support.

If status reports owned, you are done. If it reports absent, install. If it reports foreign or stale, do not install over it.

To take back only what this installation wrote:

ai-stp skill remove --target <dir> --json
ai-stp skill status --target <dir> --json

Two different skill words

Object	Page	What it is
Agent Skill CLI	this page	the procedure for driving ai-stp
Component kind skill	skill	a portable agent workflow inside a setup

skill install does not publish a component. component skill validate does not install this file. Catalog search for kind skill does not tell you whether this destination is owned.

skill status

Report what Agent Skill is at a destination and who owns it.

ai-stp skill status --target <dir> --json

Creates nothing, including the destination directory.

state is one of:

state	Meaning
absent	no skill file is there
owned	this installation wrote it, and the digest still matches
foreign	something else put a skill there; it is not ours to replace
stale	this installation wrote it, and someone edited the file afterwards

skill install

Install the canonical Agent Skill at a named destination.

ai-stp skill install --target <dir> --json

Writes a package (SKILL.md plus references/) and its ownership record. It refuses to replace a skill this installation did not write (foreign) and refuses to overwrite a package that was edited after this installation wrote it (stale).

Idempotent on an owned destination: installing the same package again rewrites the same bytes and the answer is unchanged.

--harness installs the native projection for one harness instead of the canonical map. The projection still carries the procedure; it does not point at a repository path. --locale ru installs the Russian procedure. Read the descriptor before adding either option.

skill remove

Remove the Agent Skill this installation put at a destination.

ai-stp skill remove --target <dir> --json

Removes only what the ownership record claims. A file this CLI did not write is left alone and said so (AI_STP_CONFLICT). The local registry and anything the user set up are a different thing and are never touched: this is the control plane, not their data.

Removing an absent destination is a successful no-op: state stays absent.

What a successful envelope contains

All three commands return the same result shape in data:

Field	What it is
state	absent, owned, foreign, or stale
target	the destination directory, as displayed
digest	the package digest, or null
harness	the projection that was installed, or null for canonical
locale	en or ru when this installation wrote the package
files	owned relative paths of the package
available_harnesses	harnesses this build can project for
schema_version	the schema major of this report

The envelope also carries ok, warnings, next_actions, request_id, operation_id, and schema_version.

foreign can appear on a successful status. It is not a success on install or remove: those refuse with AI_STP_CONFLICT.

What these commands never do

• install a skill component into a setup;
• guess the harness skill directory when --target is missing;
• overwrite a foreign or stale file;
• touch the local registry, passports, or cached catalog bytes;
• start an agent session or call a model API;
• write a harness target.

After the file is present, the agent still starts every session with:

ai-stp task intents --json

The Skill tells it to do that. Installing the file is not a substitute for compact intent discovery.

Typical refusals

What you see	What it means	What to do
AI_STP_VALIDATION_ERROR missing --target	a destination directory is required	pass --target <dir>
AI_STP_VALIDATION_ERROR unknown harness	no projection is shipped for that name	capabilities --json and use a supported harness
AI_STP_CONFLICT on install, foreign	a skill this installation does not own is already there	skill status --target <dir> --json; do not overwrite it
AI_STP_CONFLICT on install, stale	the installed skill was edited after this installation wrote it	skill remove --target <dir> --json only if you mean to discard those edits
AI_STP_CONFLICT on remove	that skill was not installed by this installation	leave it; this is not yours to delete
searching the catalog for a skill	that is kind skill, a component	skill components

Related pages

Page	Why
skill components	the other meaning of skill
Observe	doctor and help --agent after install
Harness program	the program that will read this file
Toolchain	a different missing-first-run object
Component commands	adopt and publish kind skill
Quickstart for agents	the Agent Skill step of first run

Flags from ai-stp help --agent --json

If help --agent disagrees with a flag on this page, the CLI wins. Optional flags are not listed here. Read them from the descriptor. Every command here requires --target.