`agent`

An agent describes a specialised role inside a harness: its area of responsibility, its inputs, its limits, the tools it may use, and the result expected of it.

An agent answers the question: which named role should carry this class of work?

It does not answer "how should that role do the work?" (), "what standing rules apply to everyone?" (), or "which package extends the harness?" ().

An agent component is not a setup of its own. It belongs to one harness's setup and inherits its boundaries.

!!! warning "Kind agent is not AGENTS.md, and not the CLI Agent Skill"

A file named AGENTS.md is the cross-harness instruction convention. Kind agent is a role definition, usually a file under an agents/ directory.

The CLI also ships one canonical Agent Skill that teaches an agent how to drive ai-stp itself. That object is installed with . It is not a catalog component and it is not this kind.

Neighbours

Choose agent when you need a bounded role with a checkable result. Choose skill when you need the procedure that role will follow. Choose instruction when the text applies without a role name.

Recommended package structure

agent is declarative. --language is none. A role is usually a single Markdown file. Claude Code authors agents as files in a directory-shaped layout; adoption accepts that single file without an extra wrapper manifest.

Portable package (what discover / adopt transfer from source/):

reviewer/
└── reviewer.md                    # {name}.md at the package root

When you start from ai_stp, scaffold first. The authoring directory is wider than the published package: discover / adopt transfer source/ when portable and projections/<harness>/ when a harness was selected, not the whole tree. Codex agents are TOML under agents/.

reviewer/                          # component-scaffold/3
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    └── reviewer.md

ai-stp component scaffold plan \
  --type agent \
  --language none \
  --harness portable \
  --name reviewer \
  --output ./reviewer \
  --json

ai-stp component scaffold apply \
  --type agent \
  --language none \
  --harness portable \
  --name reviewer \
  --output ./reviewer \
  --expected-plan-digest <digest> \
  --json

--language for an agent is none. The kind is declarative.

Describe the purpose of the role, the tools it may use, what a finished result looks like, and when to call it. Do not describe a global replacement for every instruction, secrets, or permission to change the outside world unconfirmed.

There is no ai-stp component agent validate. Structural readiness is component passport validate. Kind-specific specification checking exists only for .

Standards and frameworks

There is no independent agent-role specification comparable to the Agent Skills Specification. A skill is the portable workflow; an agent is the role.

Cite layout_source from ai-stp component discover --json when classification is uncertain. Codex custom agents are documented only from .codex/agents — do not invent a second directory.

NVIDIA SkillSpector and Cisco Skill Scanner are skill scanners. They are not this kind's validator.

Native layouts per harness

Discovery only reports layouts that are declared. Exact paths on a machine come from ai-stp component discover --json. Each finding carries layout_source. If classification is uncertain, show that field; do not guess a neighbour's path.

From the discovery matrix:

Inside a proven Claude Code plugin, discovery reads agents (each child is one agent). Inside a proven Cursor plugin, the same applies. The walker does not invent agent files from an adjacent directory.

A single file in a directory-shaped layout needs no extra manifest — that is how Claude Code agents are authored, and adoption accepts them.

ai-stp component discover --root . --json
ai-stp toolchain harness-capabilities --json

Versions are `X.Y`, not SemVer

A published agent version is immutable and has the form X.Y. There is no patch number. Changing the role text, its tools, or its limits is a new version. Updating an agent inside a setup is a new setup version.

ai-stp component version list --id <stable_id> --json
ai-stp component version release --id <stable_id> --json

--major opens the next major line. A major line is a separate access boundary.

What `ai_stp` checks

The catalog percent and the required-versus-optional split are explained on Security checks. For an agent, expect at least:

• structure, digest, license, tags, source repository;
• bounded unpack and path denylist;
• secret scanning (secrets_heuristic, and Gitleaks when enabled);
• prompt-injection and hidden-content rules;
• language SAST and SCA when scripts and lockfiles are present.

A passed scan reduces known risk. It is not a guarantee that the role is harmless. Required checks that fail or cannot run block publication.

Before install, also look at:

author_verified and component_verified are independent. Neither is a safety guarantee.

Related CLI commands

Only commands that exist. Flags always from the CLI pages, and always --json. The executable is ai-stp (package ai-stp-cli). There is no component inspect and no setup show. The only kind-specific validate is ai-stp component skill validate.

This kind, specifically: there is no component agent validate. Use passport validation.

ai-stp component passport validate --id <stable_id> --json

Not this kind — CLI Agent Skill (see Agent Skill CLI):

ai-stp skill status --json

Author, adopt, publish:

ai-stp component discover --root . --json
ai-stp component adopt --path <source_path> --json
ai-stp component passport validate --id <stable_id> --json
ai-stp component version release --id <stable_id> --json
ai-stp publication plan --id <stable_id> --version 1.0 --json
ai-stp publication confirm --plan-id <id> --plan-hash <hash> --confirm --json

Find, select, install:

ai-stp registry search --kind component --query <name> --json
ai-stp select eligibility --harness <id> --json
ai-stp install plan --json

An agent can also be an embedded member of a compose manifest. See Setups.

How an agent moves through `ai_stp`

=== "Author" The author publishes the role from a public GitHub source, or imports it locally. The version pins an exact commit and subpath.

=== "Catalog" The catalog shows the role, the supported harnesses, the constraints, the author's trusted status and the component's own independent status.

=== "Compiler" The compiler checks whether the harness supports that agent surface and that the file structure suits the provider's projection.

=== "Provider" The provider creates the native description of the role only after a plan, a digest and a confirmation. Status shows which roles are active and where they came from.

Red flags

• Treating AGENTS.md as kind agent.
• Treating ai-stp skill install as if it published this component.
• A role with no limits, no expected result, and every tool enabled.
• Codex agents from anywhere except .codex/agents.
• Live tokens, private keys, or .env bodies in the package.
• Instructions to ignore previous instructions or to widen permissions at runtime.
• experimental trust line without consent allow.
• Harness not in the component's compatibility list.
• "Latest" or a branch name instead of an exact X.Y and commit.
• Treating author_verified as component_verified.
• A subagent that is allowed to change the outside world without a confirmation path.

??? question "Can an agent be used without publishing it" Yes. Your own, imported or exactly pinned agent can be used after local checks. It does not thereby become platform-verified, and it must be shown as exactly what it is: a local or pinned object (local_owner_or_pinned).

Author checklist

1. Scaffold with --type agent --language none and keep the Markdown at the package root (under source/ in the authoring tree).
2. Name the role, its limits, its tools, and what "done" looks like. Put standing rules in and procedures in .
3. Declare authorization needs in the passport. No secrets.
4. Run ai-stp component discover --root . --json and read layout_source on the finding.
5. component adopt --path <exact source_path> — add --kind agent if the path is claimed by more than one kind.
6. Pin an exact public GitHub commit and subpath.
7. component passport validate → component version release to mint immutable X.Y.
8. Publish through the publication path.
9. In a setup, pin that X.Y. Updating later is a new setup version.

Related: Authoring, Components, , , CLI Agent Skill.