Manifest

Manifest Schema

The manifest.json file is a JSON object that declares the package identity, contents, configuration, and compatibility. Installers MUST parse this file to determine how to install and register the package.

Top-Level Fields

Field	Required	Type	Constraints	Description
spec_version	REQUIRED	string	Date format YYYY-MM-DD	The ccpkg specification version this package conforms to.
name	REQUIRED	string	1–64 characters. Lowercase alphanumeric and hyphens. MUST NOT start or end with a hyphen. MUST NOT contain consecutive hyphens.	The package identifier. Used as a namespace prefix for commands and config.
version	REQUIRED	string	Valid semver string.	The package version.
description	REQUIRED	string	1–1024 characters.	A human-readable description of the package.
author	REQUIRED	object	See Author Object.	The package author.
license	OPTIONAL	string	SPDX license identifier or "SEE LICENSE IN <filename>".	The package license.
repository	OPTIONAL	string	Valid URL.	URL to the source repository.
homepage	OPTIONAL	string	Valid URL.	URL to the package homepage.
scope	OPTIONAL	string	One of "user", "project", "any". Default: "any".	The author’s recommended install scope.
components	REQUIRED	object	See Components Object.	Declares the package contents.
config	OPTIONAL	object	See Config Object.	Declares configuration slots for user-supplied values.
compatibility	OPTIONAL	object	See Compatibility Object.	Declares host compatibility constraints.
targets	OPTIONAL	object	See Targets Object.	Tool-specific adapter mappings.
checksum	OPTIONAL	string	Format: "sha256:<hex>". 64 hex characters after prefix.	SHA-256 hash computed over the raw archive bytes (the .ccpkg ZIP file), excluding the checksum field itself from the manifest before hashing. See Checksum Verification.

Author Object

Field	Required	Type	Description
name	REQUIRED	string	The author’s name or organization.
url	OPTIONAL	string	URL to the author’s profile or website.
email	OPTIONAL	string	Contact email address.

Components Object

The components object declares which component types are included in the archive. All fields are OPTIONAL. If a field is present, the referenced paths MUST exist in the archive.

Field	Type	Description
skills	string[]	Paths to skill directories. Each directory MUST contain a SKILL.md file conforming to the Agent Skills specification.
agents	string[]	Paths to agent directories. Each directory MUST contain an AGENT.md file.
commands	string[]	Paths to command definition files.
hooks	string	Path to a hooks.json file within the archive.
mcp	string	Path to an .mcp.json template file within the archive.
lsp	string	Path to an .lsp.json template file within the archive.
instructions	string or object	Instructions declaration. A string is a path to a single instructions file. An object declares a base file and optional per-host overlays for assembly. See Instructions.

Each component field that accepts an array (skills, agents, commands) supports two declaration forms:

1. Simple form (string): A path to the component. The component is available on all hosts.
2. Structured form (object): An object with path and optional metadata fields. Use this to scope components to specific hosts.

Structured form fields:

Field	Required	Type	Description
path	REQUIRED	string	Path to the component (same as the simple form string value)
hosts	OPTIONAL	string[]	List of host identifiers on which this component should be installed. If omitted, the component is installed on all hosts.

Example with per-component host scoping:

{
  "components": {
    "skills": [
      "skills/universal-skill",
      {
        "path": "skills/claude-specific-skill",
        "hosts": ["claude-code"]
      }
    ],
    "hooks": "hooks/hooks.json",
    "agents": [
      "agents/universal-agent",
      {
        "path": "agents/copilot-agent",
        "hosts": ["copilot-cli"]
      }
    ]
  }
}

When an installer encounters a component scoped to hosts that do not include the active host, it MUST skip that component silently. The installer MUST NOT treat this as an error.

Config Object

The config object defines configuration slots that users populate at install time. Each key is a configuration variable name; the value is a config slot definition.

Config variable names MUST match the pattern [A-Z][A-Z0-9_]* (uppercase letters, digits, and underscores, starting with a letter). This convention matches environment variable naming, ensuring config values can be directly mapped to process environment variables during template substitution.

Config Slot Definition

Field	Required	Type	Constraints	Description
type	REQUIRED	string	One of "secret", "string", "number", "boolean", "enum", "path".	The value type.
description	REQUIRED	string	Max 512 characters.	Human-readable description of this config slot.
required	OPTIONAL	boolean	Default: false.	Whether the user MUST provide a value.
default	OPTIONAL	varies	Must match the declared type.	The default value if the user does not provide one.
values	Conditional	string[]	REQUIRED when type is "enum".	The set of allowed values.

Config type semantics:

Type	JSON Type	Description
secret	string	Sensitive value (API key, token). MUST be masked in logs and output. MUST NOT be stored in lockfiles.
string	string	Arbitrary string value.
number	number	Numeric value (integer or floating-point).
boolean	boolean	Boolean value (true or false).
enum	string	One of a fixed set of string values defined in values.
path	string	A filesystem path. Installers SHOULD validate that the path exists.

Compatibility Object

The compatibility object declares version constraints for host tools. Each key is a tool identifier; the value is a semver range string.

{
  "compatibility": {
    "host-a": ">=1.0.0",
    "host-b": ">=0.5.0"
  }
}

Keys are host identifiers as defined in individual adoption specifications. Installers SHOULD warn the user if the host does not satisfy the declared compatibility constraint. Installers MUST NOT refuse installation solely based on an unrecognized tool identifier.

Targets Object

The targets object provides tool-specific overrides and adapter mappings. Each key is a tool identifier. The value is an object with tool-specific configuration.

The following standard fields are defined. Tool-specific adapters MAY define additional fields.

Field	Type	Description
instructions_file	string	OPTIONAL. Filename to which assembled instructions are written for this host.
hook_events	object	OPTIONAL. Maps canonical event names (lowercase-hyphenated keys) to host-native event name strings.
mcp_env_prefix	string	OPTIONAL. Environment variable prefix for MCP server credential injection. See the host’s adoption specification for the specific prefix.

{
  "targets": {
    "<host-id>": {
      "instructions_file": "HOST-INSTRUCTIONS.md",
      "hook_events": {
        "pre-tool-use": "HostPreToolEvent",
        "post-tool-use": "HostPostToolEvent",
        "session-start": "HostSessionStart"
      },
      "mcp_env_prefix": "HOST_MCP_"
    }
  }
}

Each key is a host identifier matching an adoption specification. The hook_events mapping translates canonical event names to host-native event names; the instructions_file declares the filename to which assembled instructions are written. Missing canonical events in a host’s hook_events mean the host has no equivalent — hooks using those canonical names are silently skipped on that host. See individual adoption specs for the complete event mappings, instruction filenames, and MCP prefixes for each host.

Example Manifest

{
  "spec_version": "2026-02-14",
  "name": "api-testing",
  "version": "1.0.0",
  "description": "Skills and tools for API testing workflows, including OpenAPI validation, request generation, and mock server management.",
  "author": {
    "name": "Example Org",
    "url": "https://github.com/example-org"
  },
  "license": "MIT",
  "repository": "https://github.com/example-org/api-testing-ccpkg",
  "scope": "project",
  "components": {
    "skills": [
      "skills/openapi-validator",
      "skills/request-generator"
    ],
    "commands": [
      "commands/run-tests.md"
    ],
    "hooks": "hooks/hooks.json",
    "mcp": "mcp/.mcp.json",
    "instructions": {
      "base": "instructions/base.md",
      "hosts": {
        "claude-code": "instructions/hosts/claude-code.md",
        "copilot-cli": "instructions/hosts/copilot-cli.md"
      }
    }
  },
  "config": {
    "API_BASE_URL": {
      "type": "string",
      "description": "Base URL for the target API.",
      "required": true
    },
    "API_KEY": {
      "type": "secret",
      "description": "Authentication key for the target API.",
      "required": true
    },
    "ENVIRONMENT": {
      "type": "enum",
      "description": "Target environment for API requests.",
      "values": ["development", "staging", "production"],
      "default": "development"
    }
  },
  "compatibility": {
    "claude-code": ">=1.0.0"
  },
  "targets": {
    "claude-code": {
      "instructions_file": "CLAUDE.md"
    },
    "codex-cli": {
      "instructions_file": "AGENTS.md"
    }
  },
  "checksum": "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}