Author primitives

A package’s .apm/ directory contains primitives. Author each piece of agent context once; APM projects it onto the targets that support that primitive. See the targets matrix for the full map.

Primitive types

Primitive	One-liner	Page
Skills	Self-contained capability bundles with SKILL.md + scripts + assets	Skills
Prompts	Reusable prompt templates with frontmatter	Prompts
Instructions	Long-lived behavior rules (style guides, conventions)	Instructions and agents
Agents	Personas with explicit scope, tools, and triggers	Instructions and agents
Hooks	Event handlers fired by the runtime (pre-commit, on-tool-use, …)	Hooks and commands
Commands	Slash-command shortcuts the developer types into the agent UI	Hooks and commands
MCP servers	Tool-server declarations consumers can wire into their harness	MCP as a primitive

On-disk layout

.apm/
  skills/
    my-skill/
      SKILL.md
      scripts/
      references/
      assets/
  prompts/
    review.prompt.md
  instructions/
    style.instructions.md
  agents/
    cli-logging-expert.agent.md
  hooks/
    pre-commit.json

Commands ship as prompts (.apm/prompts/*.prompt.md); there is no separate .apm/commands/ directory. See Hooks and commands.

Markdown-based primitive types use a markdown file (or directory containing a primary markdown file). Frontmatter requirements vary by primitive type and declare metadata such as the primitive’s name and trigger conditions. apm compile reads .apm/, applies any policy, and writes per-target output to the right directories on the target’s filesystem.

Frontmatter fence

Encode primitive Markdown as UTF-8. When a Markdown primitive has frontmatter, its opening fence of at least three hyphens (for example, ---) must be the first content on line 1; an optional UTF-8 BOM may precede it and is stripped before parsing. Without that opening fence, APM treats the document as body content and later --- lines remain Markdown horizontal rules. Malformed instruction frontmatter stops the package before deployment. Critical hidden characters decoded from metadata also prevent installation by default; --force overrides only that critical finding, while warning-level findings do not prevent installation. See apm install.

Recommended reading order

1. Skills – the densest primitive type and the one most newcomers hit first.
2. Prompts – next-most-common; how reusable templates work.
3. Instructions and agents – when behavior should persist across sessions.
4. Hooks and commands – runtime extension points.
5. MCP as a primitive – when your package needs to bring along a tool server.

When you’re ready to ship, continue to Compile and Pack a bundle.