#Quick start

There are two ways in. The scaffolder emits a project that already passes its own check; the manual path is four lines of config in an existing repository.

#Scaffold a project

The fastest start is create-agent-bundle. It prompts for a name, a template, and the host targets:

npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-pr> my-plugin

Once npm releases exist, this becomes npm create agent-bundle. Until then, use a commit SHA or PR number from the preview channel.

A run that names both a directory and a template is treated as scripted and asks nothing — the remaining values fall back to their defaults:

npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-pr> my-plugin \
  --template mcp-server \
  --targets portable,codex,claude

#Templates

Every template ships a check script (validate, build, typecheck, tests) and validates with zero diagnostics — including the AB473x migration nudges, because the templates are written against the entry conventions from the start. The mcp-server template also starts with the consumer test harness, each pool labeled with the proof level it carries.

Scaffolded projects pin agent-bundle to an exact preview tarball from the same commit the scaffolder came from, so the scaffolder and the framework it pins never disagree. See the create-agent-bundle README for every flag.

#Or write the config by hand

Describe the plugin in agent-bundle.config.ts at the project root:

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.name: stringname: 'my-plugin', 
AgentBundlePluginConfig.description?: string | undefineddescription: 'What it does.' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['plugin'],
  
AgentBundleConfig.skills?: string[] | undefinedskills: ['src/skills/*'],
  
AgentBundleConfig.hooks?: Partial<Record<"sessionStart" | "beforeTool" | "afterTool" | "stop" | "agentStart" | "agentStop" | "workspaceOpen", AgentBundleHookInput>> | undefinedhooks: { 
sessionStart?: AgentBundleHookInput | undefinedsessionStart: { 
AgentBundleHookEntry.handler: string | AgentBundlePrebuiltEntryhandler: './src/session-start.ts' } },
  
AgentBundleConfig.mcp?: AgentBundleMcpConfig | undefinedmcp: { 
AgentBundleMcpConfig.servers: Readonly<Record<string, AgentBundleMcpServer>>servers: { 
tools: {
    entry: string;
}
tools: { 
AgentBundleMcpServer.entry?: string | AgentBundlePrebuiltEntry | undefinedentry: './src/mcp.ts' } } },
});

Most projects need even less than that, because the src/ conventions fill the config in when it is silent:

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.description?: string | undefineddescription: 'Evidence-backed project tools.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'codex', 'claude'],
});

The release version comes from package.json. A plugin.version field still works as a deprecated compatibility axis, but a value that disagrees with package.json reports the AB4008 warning.

#Build, or work interactively

npx agent-bundle build --root .                 # write installable artifacts to artifact/
npx agent-bundle dev --root .                   # local workbench with live rebuilds

build validates the project and writes the artifact, plus the bin/lib package build when declared. dev serves the loopback developer Workbench and rebuilds as inputs change: project overview and diagnostics, Skill documents, the artifact tree with provenance and epoch comparison, an artifact-bound MCP playground with the raw protocol trace, a hook playground that runs the emitted wrapper, and eval runs.

#Inspect what the compiler decided

npx agent-bundle inspect --root .            # normalized config and per-target plans
npx agent-bundle inspect --root . --skills   # add the skill focus
npx agent-bundle validate --root .           # check project source

inspect reads source configuration and shows the normalized model — which is where you confirm that a convention was actually picked up.

#Install the result

Every built target directory contains a generated INSTALL.md with commands that use the bundle's real plugin and marketplace names. With the portable, codex, and claude targets built above, the host installs are:

npx agent-bundle install claude --from artifact/claude --scope user
npx agent-bundle install codex --from artifact/codex

Add cursor to targets to build artifact/cursor, and npx agent-bundle install cursor --from artifact/cursor installs it the same way. A plugin build has one INSTALL.md covering every host.

For an install-free development loop against Claude Code:

claude --plugin-dir artifact/claude plugin list --json

#Next steps

• Project structure — what each src/ root means and where output lands.
• Configuration model — every config field and what owns it.
• Skills — the first surface most plugins author.