Publisher workflow
Create a capability manifest, preview the compiled package, run local preflight checks, and publish into a checked-in registry JSON file.
$ cap init acme/my-tool
$ cap preview --json
$ cap review --run-trials --json
$ cap publish --local --registry registry/packages.json --dry-run --jsonThe current prototype publishes to a filesystem registry only. Remote marketplace publish, publisher auth, namespace verification, hosted artifact upload, payment metadata enforcement, and sandbox review workers are future work.
Use this when the package source owns its manifest.
cap init acme/my-tool
cap preview --json
cap review --run-trials --json
cap publish --local --registry registry/packages.json --jsonUse this while developing CAP locally.
node src/cap.js init acme/my-tool
node src/cap.js preview --json
node src/cap.js review --run-trials --json
node src/cap.js publish --local --registry registry/packages.json --jsonThe local publisher expects one manifest file, capability.json by default. The package should be useful to humans and explicit enough for agents to evaluate safely.
namespace/nametasks, bestFor, or capabilityCard.bestForlocal-bin or single-file-url install metadataUse local-bin for repo-local executables and development fixtures. Use single-file-url when the installable artifact is one executable file pinned by SHA-256.
local-bin manifestComputes a digest from declared bin files and writes registry source paths relative to the registry file.
{
"schema": "cap-manifest.v0",
"id": "acme/my-tool",
"name": "My Tool",
"version": "0.1.0",
"kind": "local-tool",
"summary": "Inspect and repair ExampleService config files.",
"description": "Agent-friendly CLI for ExampleService maintenance.",
"keywords": ["exampleservice", "config"],
"tasks": [
"inspect ExampleService config",
"repair ExampleService config"
],
"commands": [
{
"name": "my-tool",
"path": "bin/my-tool.js",
"safeArgs": ["--help", "doctor --json"]
}
],
"safeTrials": [
{
"command": "my-tool --help",
"writes": [],
"network": [],
"description": "Print help without reading credentials or changing state."
}
],
"install": {
"backend": "local-bin",
"source": {
"path": "."
},
"bins": {
"my-tool": "bin/my-tool.js"
}
},
"permissions": {
"filesystem": ["workspace:read"],
"network": [],
"secrets": [],
"env": [],
"spend": []
},
"skill": "skills/my-tool/SKILL.md",
"mcp": {
"tools": ["my_tool_report"]
},
"structuredOutput": true,
"publisher": {
"verified": true,
"identity": "github:acme",
"method": "github-org"
}
}single-file-url manifestRequires a pinned source.sha256. The local preflight does not download and execute remote artifacts for --run-trials.
{
"schema": "cap-manifest.v0",
"id": "acme/downloaded-tool",
"name": "Downloaded Tool",
"version": "1.0.0",
"kind": "local-tool",
"summary": "Run one downloaded executable.",
"tasks": ["run downloaded tool"],
"commands": [
{
"name": "downloaded-tool",
"path": "downloaded-tool",
"safeArgs": ["--help"]
}
],
"safeTrials": [
{
"command": "downloaded-tool --help",
"writes": [],
"network": []
}
],
"source": {
"url": "https://example.com/downloaded-tool",
"sha256": "replace-with-artifact-sha256"
}
}Each publisher command has a narrow role. The JSON output is meant for agents, CI jobs, and review tooling.
cap initCreate the manifest.cap init [package-id] [--manifest <path>] [--force] [--json]Creates capability.json. It infers package metadata, package.json bins, nearby skills, MCP server names from .mcp.json, and default safe trials using --help.
cap previewCompile without writing.cap preview [--manifest <path>] [--registry <path>] [--json]Shows normalized package metadata, package summary, capability card, generated review record, install plan, and warnings for missing skill, MCP tools, or structured output.
cap reviewRun local preflight.cap review [--manifest <path>] [--registry <path>] [--run-trials] [--json]Validates manifest shape, required package metadata, safe trial commands, local bin paths, single-file URL pins, MCP tool names, skill frontmatter, and executable digests.
cap publish --localWrite the registry.cap publish --local [--manifest <path>] [--registry <path>] [--dry-run] [--force] [--json]Writes the compiled package into a local registry JSON after review passes. Publishing refuses the same id@version unless --force is set.
Blocking checks stop publish. Warnings do not block publish, but they lower package quality for autonomous agents.
single-file-url packages pin source.url and source.sha256name and description frontmatterWith --run-trials, local-bin trials run with an isolated temp HOME, CAP_HOME, and TMPDIR. CAP sets CAP_REVIEW=1 and strips common host secrets from the environment.
Use a dry-run publish in CI to prove the manifest compiles, review passes, safe trials are executable, and registry writes would succeed.
cap preview --json
cap review --run-trials --json
cap publish --local --registry registry/packages.json --dry-run --jsonnpm testThe test suite covers publish commands, review errors, single-file URL inference, object-form bins, trial isolation, and public CLI packaging.
These are the common local publish errors and the smallest fixes.
Package id must look like "namespace/name": change id to a two-part stable name.Capability card must declare at least one task: add tasks, bestFor, or capabilityCard.bestFor.Safe trial ... must start with one of this package's declared bins: make the trial command begin with a declared command/bin name.Declared bin path does not exist: fix commands[].path or install.bins.single-file-url packages must pin install.source.sha256: add the artifact SHA-256.Local publish commands require a filesystem registry path: use a local --registry path, not an HTTP URL.Remote publish is not implemented: pass --local; hosted publishing is future marketplace work.id@version already present: bump the version for meaningful changes.