Skip to content
ccpkg

Overview

ccpkg Specification

Section titled “ccpkg Specification”

Specification Version: 2026-02-22 (Draft)

Status

Section titled “Status”

This specification is a draft and is subject to change. Feedback and contributions are welcome.

Introduction

Section titled “Introduction”

ccpkg is an open packaging format for distributing AI coding assistant extensions. A ccpkg archive is a self-contained ZIP file with a declarative manifest that bundles skills, agents, commands, hooks, MCP servers, LSP servers, and configuration instructions into a single portable unit.

The format is designed around a universal core—MCP, LSP, Agent Skills, and declarative configuration—with thin, tool-specific adapters that map these universal components to the conventions of individual AI coding assistants. This architecture enables a single package to work across Claude Code, OpenAI Codex CLI, GitHub Copilot, Google Gemini CLI, and other tools that adopt the format.

For implementation guides and tooling, visit the ccpkg repository.

Notational Conventions

Section titled “Notational Conventions”

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

Relationship to Other Specifications

Section titled “Relationship to Other Specifications”

ccpkg builds on and references the following specifications:

SpecificationRole in ccpkg
Model Context Protocol (MCP)MCP server configuration and transport definitions
Agent SkillsSkill and agent component format (SKILL.md, AGENT.md)
Language Server Protocol (LSP)LSP server configuration
Semantic Versioning 2.0.0Package version numbering
SPDX License ListLicense identifiers
JSON SchemaConfig schema validation

Design Principles

Section titled “Design Principles”

The following principles guide the design of the ccpkg format. Implementors SHOULD consider these principles when making decisions not explicitly covered by this specification.

  1. Self-contained archives. Packages MUST be self-contained. Installation MUST NOT require network fetches, dependency resolution, or compilation. All executable content, configuration templates, and metadata MUST be present in the archive at packaging time.

  2. Tool-agnostic core. The format MUST be tool-agnostic at its core. MCP, LSP, and Agent Skills are universal open standards. Tool-specific behavior is expressed through thin adapter mappings, not fundamental format changes.

  3. Deterministic installation. Installation MUST be deterministic. Given the same package archive and the same user configuration, the installed result MUST be identical.

  4. No central authority. No central registry is REQUIRED. Packages MAY be distributed via any URL, file path, or registry. Registries are optional and additive.

  5. Separated configuration. User configuration MUST be separated from package contents. Secrets, preferences, and environment-specific values live outside the archive and are injected at install or load time.

  6. No install-time code execution. Packages MUST NOT execute arbitrary code during installation. There are no postinstall scripts, no build steps, and no setup hooks. The installation process is purely declarative: extract, configure, register.

  7. MCP server deduplication. When multiple packages declare MCP servers with the same identity (key name and origin), the installer SHOULD deduplicate them. The highest version wins by default. Users MUST be able to override deduplication per-server or globally.

  8. No inter-package dependencies. Inter-package dependencies are explicitly out of scope for this specification version. Each package MUST be self-contained and MUST NOT declare dependencies on other ccpkg packages. If a skill requires an MCP server, both MUST be packaged together in a single .ccpkg archive.

Architecture

Section titled “Architecture”

Overview

Section titled “Overview”

ccpkg defines a packaging and distribution pipeline that connects package authors to end users through an optional registry layer. The architecture separates concerns across five roles: Author, Registry, Installer, Host, and User.

flowchart LR
    A[Package Author] -->|creates| P[".ccpkg archive"]
    P -->|published to| R["Registry (optional)"]
    P -->|distributed via| D["URL / file path"]
    R -->|discovered by| I[Installer]
    D -->|fetched by| I
    I -->|extracts to| C[Local Cache]
    C -->|components registered in| H[Host Application]
    H -->|lazy loads at| S[Session Start]
    U[User] -->|invokes install via| I
    U -->|uses components in| H

Roles

Section titled “Roles”
RoleDescription
Package AuthorCreates the .ccpkg archive containing components and a manifest. Authors are responsible for correctness, licensing, and security of package contents.
RegistryAn OPTIONAL service or static file that indexes available packages. Registries provide discovery and version resolution but are not required for installation.
InstallerThe tool or skill that processes .ccpkg archives. The installer downloads, verifies, extracts, configures, and registers packages. The ccpkg skill itself serves as the reference installer implementation.
HostThe AI coding assistant (e.g., Claude Code, Codex CLI) that loads and uses installed components. The host is responsible for component activation and runtime integration.
UserThe person who installs and uses packages. Users provide configuration values, approve hook scripts, and control what packages are active.

Component Lifecycle

Section titled “Component Lifecycle”
stateDiagram-v2
    [*] --> Packaged: Author creates archive
    Packaged --> Downloaded: User requests install
    Downloaded --> Verified: Checksum validated
    Verified --> Extracted: Archive unpacked
    Extracted --> Configured: Config values resolved
    Configured --> Registered: Components added to lockfile
    Registered --> Idle: Session starts, metadata loaded
    Idle --> Active: Component invoked
    Active --> Idle: Invocation complete
    Registered --> Removed: User uninstalls
    Removed --> [*]

Relationship to Assistant Adoption Specifications

Section titled “Relationship to Assistant Adoption Specifications”

The ccpkg specification is structured as a layered system. This core specification defines the universal packaging format — archive structure, manifest schema, component types, install lifecycle, and security model. It is intentionally tool-agnostic: no host-specific filenames, settings paths, or plugin registration mechanisms appear in the core spec.

Host-specific integration details are captured in assistant adoption specifications, one per AI coding assistant. Each adoption spec declares how ccpkg maps to a particular host’s conventions: instruction filenames, hook event names, plugin registration steps, settings paths, and component support levels. Adoption specs are machine-validated against the Assistant Adoption Specification Schema and published alongside this specification in the spec/assistants/ directory.

The Assistant Adoption Specification defines the normative contract for what an adoption spec MUST contain. Installers use adoption specs at install time to perform host-specific adapter operations (generating plugin manifests, registering with the host, translating hook events). Package authors consult adoption specs to understand which components each host supports and how to structure portable packages.