`instruction`¶

An instruction is standing text that shapes how an agent decides: rules, project memory, working style, the limits of its authority, and harness notes that are not a workflow, a shortcut, or a package.

An instruction answers the question: what must the agent keep in mind while it works?

It does not answer "how should the agent do this class of task?" (skill), "which named shortcut do I type?" (command), or "which specialised role should run?" (agent).

AGENTS.md is an instruction, not an agent

A file named AGENTS.md is the cross-harness instruction convention. Kind agent is a role definition. Discovery will not treat AGENTS.md as a role, and it will not treat a role file as standing rules.

CODEX.md is not a documented Codex instruction layout. Discovery returns it as unsupported_manifest and points at AGENTS.md.

Memory, rules, preferences, and project conventions are content of instruction (or of setting). There is no memory kind.

Object	Kind	Lives in a setup?
`AGENTS.md` / `CLAUDE.md` / rules text	`instruction`	yes
A named role under `agents/`	`agent`	yes
CLI Agent Skill (`ai-stp skill …`)	not this kind	no

Neighbours¶

Kind	The main difference
`skill`	a skill is a repeatable procedure with supporting files; an instruction is standing context
`command`	a command is invoked by name; an instruction is already in the session
`agent`	an agent is a role that uses instructions; the instruction is the text, not the role
`plugin`	a plugin extends the harness; an instruction extends the agent's reading list
`mcp`	MCP connects a tool; an instruction may only say when that tool should be used
`hook`	a hook fires on a lifecycle event; an instruction does not run
`setting`	a setting holds parameters; an instruction holds prose

Choose instruction when the agent must follow standing rules without a procedure attached. Choose skill when the work has steps, scripts, or references. Choose command when a person should start the work by name.

Recommended package structure¶

instruction is declarative. --language is none. There is no independent instruction specification comparable to the Agent Skills Specification; the body is Markdown the harness will load as context.

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

project-conventions/
└── AGENTS.md

When you start from ai_stp, start the author intent. Do not type component scaffold plan. 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.

project-conventions/                 # component-scaffold/6
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    └── AGENTS.md

source/AGENTS.md is the canon. Claude Code projections use CLAUDE.md; Cursor uses rules/<name>.mdc. Do not invent a second wrapper directory.

Everyday:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert recovery (already-held digest):

ai-stp component scaffold plan \
  --type instruction \
  --language none \
  --harness portable \
  --name project-conventions \
  --output ./project-conventions \
  --json

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

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

Adoption accepts a path discovery already named. A directory must carry a closed-set manifest (SKILL.md, AGENTS.md, plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json, hooks.json, package.json, or pyproject.toml). A single file in a file-shaped layout — including AGENTS.md — is the component; it needs no extra wrapper.

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

Standards and frameworks¶

AGENTS.md — the cross-product instruction file. Discovery treats a project-root AGENTS.md as an instruction, not as kind agent.
Harness pages that declared a layout appear on each finding as layout_source from the author intent envelope. Show that field when classification is uncertain; do not guess a neighbour's path.
Contrast with the Agent Skills Specification when you are tempted to put a workflow into an instruction: a procedure with SKILL.md is a skill.

Do not invent a memory kind, a rules kind, or extra frontmatter the harness UI happens to display. Those are content of this kind or of setting.

Native layouts per harness¶

Discovery only reports layouts that are declared. Exact paths on a machine come from the author intent envelope. Each finding carries layout_source — the official document that declared the layout. If classification is uncertain, show that field; do not guess a neighbour's path.

From the discovery matrix:

Harness	Global	Project	Notes that are in the discovery contract
Claude Code	yes	yes	standing text; a directory under `skills/` with a plugin manifest is a plugin, not an instruction
Codex	yes	yes	`CODEX.md` is `unsupported_manifest`; use `AGENTS.md`
Pi	yes	no	global instruction only in the bounded matrix
OpenCode	no	no	not a declared instruction layout in the bounded matrix
Grok Build	no	no	not a declared instruction layout in the bounded matrix
Cursor	yes	yes	inside a proven `.cursor-plugin/plugin.json` pack, each file under `rules/` is an instruction
Antigravity	no	no	not a declared instruction layout in the bounded matrix
`undefined`	portable conventions	portable conventions	not a harness; automatic install is not considered safe

Inside a proven Cursor plugin, discovery reads rules and classifies each file as instruction. It does not invent instruction files from an adjacent directory.

Expert recovery — everyday authoring is the author intent:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Do not type component discover. The engine finds the native tree.

If the same path answers to more than one harness, name --harness on adopt. Use portable for the shared cross-product claim.

Versions are `X.Y`, not SemVer¶

A published instruction version is immutable and has the form X.Y. There is no patch number. Changing the Markdown is a new version. Updating an instruction 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 instruction, 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 (pi_content_pack, content_hidden).

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

Before install, also look at:

Check	Why it matters
Diff of the prose	an instruction can quietly widen authority
Harness compatibility	Claude-specific text must not land on an incompatible target
Scope	global rules apply more widely than a project file
Who is the author	a verified author does not make content automatically safe
Which `X.Y` is pinned	updating the text makes a new version of the setup
Trust line	`experimental` needs explicit consent

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

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 instruction validate. Use passport validation.

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

Author, adopt, publish:

ai-stp task start --intent author --idempotency-key author-session-01 --json
ai-stp task start --intent publish --idempotency-key publish-session-01 --json

If discovery reported the path under more than one harness or kind:

Expert recovery:

ai-stp component adopt --path <source_path> --harness portable --kind instruction --json

Install:

ai-stp task start --intent install --idempotency-key install-session-01 --json

Expert catalog inspect:

ai-stp registry search --kind component --query <name> --json

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

How an instruction moves through `ai_stp`¶

AuthorCatalogCompilerProvider

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

The catalog shows what it is for, the supported harnesses, the constraints, the author's trusted status and the component's own independent status.

The compiler checks that the instruction can be built into the chosen setup and that its file structure suits the provider's projection.

The provider places the instruction on the harness's native surface and updates the related indexes only after a plan, a digest and a confirmation.

Red flags¶

Treating AGENTS.md as kind agent, or a role file as standing rules.
Shipping CODEX.md and expecting discovery to accept it as Codex instructions.
Nesting the Markdown under payload/ or another wrapper directory.
Live tokens, private keys, or .env bodies in the package.
Rules that instruct the agent to ignore previous instructions or to exfiltrate secrets.
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.
Inventing a memory kind instead of putting memory in this text.
Copying files into a target instead of going through the provider plan.

Can an instruction be used without publishing it

Yes. Your own, imported or exactly pinned instruction 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¶

Scaffold with --type instruction --language none and keep the Markdown at the package root (under source/ in the authoring tree).
Write standing rules only. Move a procedure to a skill; move a named shortcut to a command.
Declare what the text asks of the agent in the passport. No secrets.
Register the directory through ai-stp task start --intent author --idempotency-key author-session-01 --json. Expert component discover / component adopt remain for recovery.
Pin an exact public GitHub commit and subpath.
component passport validate → component version release to mint immutable X.Y.
Publish through the publication path.
In a setup, pin that X.Y. Updating later is a new setup version.

Related: Authoring, Components, agent, skill.

instruction¶

Neighbours¶

Recommended package structure¶

Standards and frameworks¶

Native layouts per harness¶

Versions are X.Y, not SemVer¶

What ai_stp checks¶

Related CLI commands¶

How an instruction moves through ai_stp¶