apkg.json Schema Reference

The apkg.json file is the package manifest for every APKG package. It describes the package identity, type, dependencies, and type-specific metadata. You can create one interactively with apkg init.

Minimal example

Only three fields are strictly required:

{
  "name": "@scope/my-package",
  "version": "0.1.0",
  "type": "skill"
}

Base fields

These fields are shared by all package types.

Field	Type	Required	Default	Description
name	string	Yes	—	Scoped package identifier
version	string	Yes	—	Package version (semver)
type	string	Yes	—	Package type
description	string	No	—	Human-readable summary of the package
license	string	No	"MIT"	License identifier
keywords	string[]	No	[]	Tags for search and discovery
readme	string	No	—	Path to a README file (auto-added by apkg init if README.md exists)

name

The package name must follow these rules:

• Start with a scope: @username/name or @org/name
• Use only lowercase letters, numbers, hyphens (-), dots (.), and underscores (_)
• Start and end with a letter or number (after the scope prefix)
• Be 214 characters or fewer

If you are logged in, apkg init defaults the scope to your username (e.g. @alice/my-tool).

version

Must be a valid semver string (e.g. 0.1.0, 1.0.0, 2.3.1). Each call to apkg publish must use a version that has not been published before.

type

Determines how the package is installed, what metadata fields are available, and whether automatic tool setup runs after installation. Valid values:

Value	Description	Tool setup	Docs
skill	A reusable AI capability	Yes	Skill
agent	An autonomous agent with tool bindings	Yes	Agent
command	A slash command for AI coding assistants	No	Command
rule	A guideline or constraint for AI assistants	No	Rule
mcp-server	A Model Context Protocol server	—	—
prompt	A prompt template	—	—
config	A configuration package	—	—
library	A shared library	—	—
composite	A bundle of multiple package types	—	—

Dependencies

Dependencies map scoped package names to semver ranges. They are managed with apkg add and apkg remove.

Field	Type	Description
dependencies	object	Packages required at runtime
devDependencies	object	Packages needed only during development
peerDependencies	object	Packages expected to be provided by the consumer

Add to each category with the corresponding flag:

apkg add @acme/utils          # → dependencies
apkg add @acme/lint -D        # → devDependencies
apkg add @acme/runtime -P     # → peerDependencies

Example in apkg.json:

{
  "dependencies": {
    "@acme/utils": "^1.0.0"
  },
  "devDependencies": {
    "@acme/lint": "^0.3.0"
  },
  "peerDependencies": {
    "@acme/runtime": ">=2.0.0"
  }
}

Skill fields

Skill packages ("type": "skill") can include an optional skill object.

Field	Type	Description
skill.capabilities	string[]	List of capabilities the skill provides

{
  "name": "@acme/code-reviewer",
  "version": "1.2.0",
  "type": "skill",
  "description": "AI-powered code review",
  "license": "MIT",
  "skill": {
    "capabilities": ["code-review", "bug-detection"]
  }
}

See Skill for tool setup details.

Agent fields

Agent packages ("type": "agent") can include an optional agent object.

Field	Type	Description
agent.tools	object[]	Tools the agent depends on
agent.systemPrompt	string	Inline system prompt text, or a path to a prompt file
agent.modelPreference	string[]	Ordered list of preferred model IDs

Tool object

Each entry in agent.tools has the following shape:

Field	Type	Default	Description
name	string	—	Display name for the tool
package	string	—	Scoped package name
required	boolean	true	Whether the tool is required

System prompt resolution

The systemPrompt field can be:

• Inline text — "You are a research assistant." — used as-is.
• A file path — "prompts/system.md" — the file is read from the package directory at setup time.

Example

{
  "name": "@acme/research-agent",
  "version": "0.8.0",
  "type": "agent",
  "description": "Autonomous research agent",
  "license": "MIT",
  "agent": {
    "tools": [
      { "name": "web-search", "package": "@acme/web-search", "required": true },
      { "name": "formatter", "package": "@acme/fmt", "required": false }
    ],
    "systemPrompt": "prompts/system.md",
    "modelPreference": ["claude-sonnet-4-6"]
  }
}

See Agent for tool setup details.

Command and rule fields

Command ("type": "command") and rule ("type": "rule") packages use only the base fields. They have no type-specific metadata.

See Command and Rule for usage details.

Complete example

A full manifest for an agent package using every available field:

{
  "name": "@acme/research-agent",
  "version": "0.8.0",
  "type": "agent",
  "description": "Autonomous research agent that searches the web and synthesizes findings",
  "license": "MIT",
  "readme": "README.md",
  "keywords": ["research", "web-search", "agent"],
  "dependencies": {
    "@acme/web-search": "^1.0.0",
    "@acme/fmt": "^0.5.0"
  },
  "devDependencies": {
    "@acme/test-harness": "^2.0.0"
  },
  "agent": {
    "tools": [
      { "name": "web-search", "package": "@acme/web-search", "required": true },
      { "name": "formatter", "package": "@acme/fmt", "required": false }
    ],
    "systemPrompt": "prompts/system.md",
    "modelPreference": ["claude-sonnet-4-6"]
  }
}

Related pages

Page	Description
apkg init	Create a manifest interactively
apkg publish	Pack and upload to the registry
apkg add	Add dependencies to the manifest
Package Types	How the type field determines package behavior