For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/reference/targets-artifacts.md.
Skip to main content
agent-bundle
  • English

      • Targets and artifacts

      Start with the target and capability map to choose a surface. The generated host matrix records feature support and evidence. This page describes what is emitted and which object downstream tools consume.

      The composite plugin root

      agent-bundle build writes one composite artifact root, artifact/ by default. output.distPath or CLI --output moves the root; it does not redesign the layout inside it. The five built-in projections are amp, claude, codex, cursor, and portable.

      Omitting targets selects only portable. An explicit selection can combine built-in projections when the authored components satisfy their compatibility rules. Target order does not change the result. plugin, web, npm, and browser presentation profiles are not extra built-in targets.

      The following is an illustrative combined layout, not a promise that an empty plugin emits every file. Read the generated manifest for the actual executable names and included components.

      artifact/
├── .amp/plugins/<name>/
│   ├── index.js                       # native Amp factory
│   ├── skills/                        # explicitly registered Skills
│   └── hooks/                         # mapped callbacks' executable support
├── .claude-plugin/plugin.json
├── .claude-plugin/marketplace.json
├── .codex-plugin/plugin.json
├── .codex-plugin/hooks.json
├── .codex-plugin/mcp.json
├── .agents/plugins/marketplace.json
├── .cursor-plugin/plugin.json
├── .cursor-plugin/hooks.json
├── .cursor-plugin/mcp.json
├── .mcp.json                          # Claude MCP document
├── plugin.json                        # portable manifest
├── mcp.json                           # portable MCP document
├── hooks/hooks.json                   # Claude hook document
├── hooks/                             # compiled, host-bound wrappers/workers
├── mcp/                               # compiled MCP entries and workers
├── bin/                               # generated CLI / configured web command
├── skills/, commands/, rules/
├── scripts/, assets/, mcp-apps/
├── INSTALL.md
├── install.mjs                        # selected Cursor/portable install path
├── agent-bundle.manifest.json
└── agent-bundle.compile-evidence.json

      Shared root components are emitted once. Amp's directory plugin keeps its registered Skills and execution support inside its nested directory so the installed copy is self-contained. The native Amp install root is therefore not the same directory as the composite artifact root.

      A static Skills-only plugin does not need empty MCP servers or a Flight/state process. Some empty native hook/MCP documents are intentional discovery-isolation barriers when another selected host has content at a conventional fallback path. Do not delete those barriers as unused files.

      Where each host reads its documents

      TargetEntry or manifestHook registrationMCP configurationMarketplace
      amp.amp/plugins/<name>/index.jsNative PluginAPI callbacksSkill-scoped mcp.json beside an explicitly registered SkillNone generated
      claude.claude-plugin/plugin.jsonhooks/hooks.json.mcp.json.claude-plugin/marketplace.json
      codex.codex-plugin/plugin.json.codex-plugin/hooks.json.codex-plugin/mcp.json.agents/plugins/marketplace.json
      cursor.cursor-plugin/plugin.json.cursor-plugin/hooks.json.cursor-plugin/mcp.json.cursor-plugin/marketplace.json when requested
      portableplugin.jsonNo native-hook component in the formatmcp.jsonNone generated

      Paths are stable across valid single-target and multi-target selections. Codex and Cursor use explicit pointers to avoid loading another projection's fallback documents. A third-party portable client can have different precedence and supported subsets; consult its individual record in the host matrix, not this native-layout table.

      Hook wrappers

      A compiled hook wrapper belongs to its selected host codec and contract. The same source hook can therefore produce several wrappers. Config-declared hooks reaching one host use the plain name; those reaching multiple hosts use host-qualified names. Conventional semantic events and standalone workers are also recorded in executables.hooks.

      Use hooks list and the manifest rather than constructing wrapper filenames. The native event, payload provenance, matcher and return semantics are in the event matrix. Explicit targets and supported event requires declarations affect selection; neither can manufacture an event or decision the host cannot express.

      Compiled surfaces

      Generated MCP entries, scripts, CLI bins and browser Apps are attributed to the composite selection, not independently rebuilt as unrelated applications for each host. An Agent Document renderer and a browser App compilation are distinct environments.

      Amp's MCP projection is skill-scoped. Its current adapter permits supported remote servers and globally resolvable command servers associated with exactly one bundled Skill; it rejects compiler-owned local MCP entries without a supported native path/cwd contract. Listing Amp as a target does not make the ordinary local generated-MCP starter valid for Amp.

      A configured web surface adds the framework-owned command to bin/<plugin>.mjs, even without an authored CLI command. It is a local browser host for declared MCP Apps, not a web output target, a separate generated web/ application, or permission to bypass App consent.

      One root, one set of bytes

      DiagnosticConstraint and recovery
      AB4103Selected projections disagree on the bytes at a shared path. Make the shared component compatible or build the conflicting projections separately. Target ordering never authorizes overwriting it.
      AB4105A host-scoped command/rule would be discovered by another selected host. Correct the scope/content or separate the artifacts. Distinct filenames alone do not prove discovery isolation.
      AB4106An advanced third-party adapter is combined with another target. The current custom-adapter contract requires an isolated single-target build; registering an adapter under a built-in name does not grant the built-in layout guarantees.

      Skills are shared by the selected targets. A host extension that changes the generated Skill bytes can still produce a real AB4103 conflict. An explicit rejection is safer than shipping a composite whose effective behavior depends on which host discovers it first.

      The root is distributable

      A copied composite artifact needs no per-host recompilation. It carries its generated installation instructions and the required installation support. npm delivery still needs an npm packaging step using the generated npm root; a directory build is not already a tarball.

      Selected targetSupported installation direction
      ampInstall the nested generated directory under the documented project/user plugin location; reload through the host's documented interactive action.
      claudeNative marketplace registration and plugin installation from the declared composite root.
      codexNative marketplace registration and plugin addition from the declared composite root.
      cursorReceipt-owned local copy or the explicitly selected marketplace workflow.
      portableFollow the recorded reader's instructions. The included install.mjs is the documented Cursor-compatible path, not a universal installer for every portable reader.

      The framework's install --from resolves the selected native location from the composite root. Consumers can follow INSTALL.md without installing the compiler. A plugin may additionally provide a thin package-bound bin through agent-bundle/install; that entry is opt-in, not automatically generated for every package.

      With package output enabled, dist/ is a complete npm root: a copy of the validated composite, package.json, standard package documents, and declared package-only entries. A generated routed CLI is copied unchanged and referenced as bin/<name>.mjs. An authored package bin instead compiles to bin/<name>.js. There is no required nested artifact/ directory inside the tarball. See shipping for prepack, actual npm pack, and installed-bin proof. npm installation does not automatically register a plugin with a host.

      agent-bundle.manifest.json

      The current closed artifact contract is manifestVersion: 6. It is the index of the built application, not another file the plugin author maintains.

      SectionResponsibility
      application, runtimePlugin identity/version and the selected generated-executable Node floor.
      filesEmitted file inventory, kinds, sizes, digests and applicable modes.
      projectionsSelected host bindings and pointers to native documents/entries.
      routesCanonical operation, contract, CLI projection, event, layout and provider records.
      executablesThe exact bins, hooks, MCP servers and scripts, including canonical launch bindings where applicable.
      distributionChannels, installation support and declared prebuilt payload requirements.
      compilerProducer, source/provenance, adapter and validation evidence, separately versioned from the public artifact contract.
      webOptional declared App exposure and policy referencing the existing server/App records. It does not contain a second copy of the server entry, argv or environment.

      For compiled/prebuilt MCP servers, canonical launch arguments distinguish artifact references from literal values. A slash in a literal does not make it a relocatable artifact path. The launcher expands only the supported declared tokens at the appropriate boundary.

      The web.apps rows contain App identity, server association, allowed capabilities and optional opening tool/input. Launch selection comes from the corresponding executable/projection record. Do not reconstruct it from browser-profile selection or add entry, args, and env to each web App. The exact field definitions are in Artifact manifest.

      The compiler emits both the native documents and the canonical manifest. Structural validation, canonical representation, referenced-file checks and content digests have distinct roles; a reader that parses the manifest is not necessarily running every artifact-validation check. Use the appropriate public validation command, and do not change digests to bless modified output.

      Persisted agent-bundle.compile-evidence.json binds compiler evidence to emitted bytes. A matching hash is not a universal proof about reflective or unanalyzed runtime loading. Residual checks and prebuilt dependency declarations remain necessary where compiler evidence cannot establish self-containment. See validation.

      Versions and revisions

      Keep source package version, built artifact version, installed artifact version and observed running-server version distinct when collecting evidence. The installed-host proof compares the relevant observations; absent observations must not be invented.

      An adapter revision and its observed native-host version describe a different contract from the plugin's own release version. The compiler record also has an independently versioned shape. Do not update a private manifest reader independently of the compiler that emits its input. Use a compatible public compiler/runtime/lifecycle package set and validate the actual deliverable.

      prepack checks the applicable package/manifest version and dependency evidence. A dependency inlined into generated JavaScript is not automatically a consumer runtime dependency; prebuilt payloads, declarations and supported install scripts can establish real requirements.

      Next