Manifest Specification

The bpm.json file defines your package metadata, compatibility, and behavior.

{
  "name": "my-package",
  "version": "1.0.0",
  "type": "convention",
  "description": "A short description of what this package does",
  "entry": "SKILL.md",
  "scope": "session",
  "token_cost": 2400,
  "keywords": ["workflow", "productivity"],
  "author": {
    "name": "Your Name",
    "github": "your-username"
  },
  "license": "Apache-2.0",
  "repository": "https://github.com/you/your-package",
  "agents": ["goose", "claude-code", "codex", "cursor"],
  "dependencies": [],
  "conflicts": [],
  "peers": []
}

namestringrequired

The package name. Must be lowercase, alphanumeric with hyphens. Unique across the registry. First-come-first-served.

versionstringrequired

Semantic version (semver). Used for version resolution and update detection.

typeenumrequired

Determines how the package integrates with the agent.

convention

Behavioral rules that shape how the agent acts. Loaded into context as markdown. Changes posture, not capability.

e.g., learning-mode

extension

MCP server providing callable tools. Registered in the agent's runtime and invoked during sessions.

e.g., timbre

template

Scaffolding for new projects. Copied into the user's workspace and customized. Not loaded into agent context.

e.g., production-agent-workflow

measurement

Instruments that track agent or user behavior. Typically an extension paired with a convention for analysis and reporting.

e.g., rp-why

descriptionstringrequired

A concise description shown in search results and package cards. Keep under 120 characters.

entrystringrequired

Relative path to the main content file. For conventions, this is typically a markdown file (e.g., SKILL.md). For extensions, the server entry point.

scopeenum

When the package should be active. Defaults to "session".

global

Always loaded regardless of project or session. Use for identity, core boundaries, and safety constraints.

project

Loaded when working in this project. Use for team conventions, project-specific workflows, and shared norms.

session

Loaded only when explicitly activated. Use for behavioral modes that shift agent posture on demand.

path

Loaded when tools touch specific directories. Use for module-specific conventions within a monorepo.

token_costnumber

Approximate tokens consumed when loaded into agent context. Helps users budget their context window. Conventions and extensions that inject text should include this.

keywordsstring[]

Tags for search and discovery. Up to 10 keywords.

authorobjectrequired

Object with "name" (display name) and "github" (GitHub username). Must match your registry login to publish.

licensestring

SPDX license identifier. Defaults to Apache-2.0 if omitted.

repositorystring

URL to the source repository. Displayed on the package detail page and used by the CLI for installation.

agentsstring[]required

List of compatible agents. Valid values: "goose", "claude-code", "codex", "cursor". Determines which agents can use this package.

dependenciesstring[]

List of other bpm package names required for this package to work. Installed automatically.

conflictsstring[]

List of package names that contradict this package's behavior. bpm warns if conflicting packages are both installed.

peersstring[]

List of package names that enhance this package (optional, not required). Shown as recommendations on the package detail page.