Ccpkg

Spec Version Status License: CC-BY-4.0 Docs GitHub Discussions

An open packaging format for AI coding assistant extensions.

ccpkg is a self-contained archive format for packaging and distributing skills, agents, commands, hooks, MCP servers, and LSP servers as a single portable unit. One file, one install, zero post-install steps.

The Problem

AI coding assistants are increasingly extensible, but sharing extensions is fragmented:

• Brittleness -- Extensions installed from Git repos break silently when authors push changes. No version pinning, no integrity verification, no dependency vendoring.
• Slow startup -- Every session start fetches plugin state from remote repos. Multiple plugins mean minutes of latency before the assistant is ready.
• No trust signals -- Finding good extensions means word-of-mouth. No curation, no verification, no structured metadata to filter by.
• Configuration burden -- MCP server configs end up buried in plugin cache directories. Secrets, env vars, and auth tokens require editing opaque files.

The Solution

A .ccpkg file is a standard ZIP archive containing a declarative manifest.json and all extension components. Install is deterministic: extract, configure, register. No post-install scripts, no network fetches, no build steps.

example-plugin-1.0.0.ccpkg (ZIP)
├── manifest.json           # Package identity, components, config
├── skills/                 # SKILL.md files (Agent Skills format)
├── agents/                 # AGENT.md files
├── commands/               # Slash command definitions
├── hooks/                  # Event handlers (hooks.json + scripts)
├── mcp/                    # MCP server config template
├── lsp/                    # LSP server config template
├── instructions/           # INSTRUCTIONS.md + tool-specific mappings
└── LICENSE

Key Features

• Self-contained archives -- All dependencies vendored inside. No runtime network fetches.
• Cross-tool portability -- Works across Claude Code, Gemini CLI, Codex, Copilot, and other compatible tools. Built on universal standards (MCP, LSP, Agent Skills).
• Lazy loading -- Only metadata loaded at startup. Full content loaded on demand. Twenty installed packages have the same startup time as zero.
• Typed configuration -- Manifest declares config slots (secrets, strings, enums, paths). Users configure once at install time. Templates wire values into MCP/LSP configs automatically.
• Deterministic lockfiles -- ccpkg-lock.json pins exact versions with checksums. Commit it to share identical environments across a team.
• Decentralized registries -- No central authority required. Registries are JSON files hostable on GitHub Pages, S3, or any static server.
• Install scope control -- User flag always wins. Install globally (~/.claude/packages/) or per-project (<project>/.claude/packages/).
• Dev mode -- Symlink local directories for live development without re-packing.

Built On Open Standards

Standard	Role in ccpkg
Agent Skills	Skill format (SKILL.md)
Model Context Protocol	MCP server configuration
Language Server Protocol	LSP server configuration
Semantic Versioning	Package versioning
JSON Schema	Manifest validation

Documentation

Document	Description
Specification	Formal format definition (RFC 2119 conventions)
Design Document	Rationale and decisions behind the design
Manifest Schema	Machine-readable JSON Schema for manifest.json

Example Manifest

{
  "spec_version": "2026-02-14",
  "name": "api-testing",
  "version": "1.0.0",
  "description": "Skills and tools for API testing workflows.",
  "author": {
    "name": "Example Org",
    "url": "https://github.com/example-org"
  },
  "license": "MIT",
  "scope": "project",
  "components": {
    "skills": ["skills/openapi-validator", "skills/request-generator"],
    "commands": ["commands/run-tests.md"],
    "hooks": "hooks/hooks.json",
    "mcp": "mcp/.mcp.json",
    "instructions": "instructions/INSTRUCTIONS.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
    }
  },
  "targets": {
    "claude": { "instructions_file": "CLAUDE.md" },
    "codex": { "instructions_file": "AGENTS.md" }
  }
}

Status

This specification is a draft (version 2026-02-14). The format is stable enough for experimentation and feedback but may change before 1.0.

Contributing

Feedback and contributions are welcome:

• Open an issue for bug reports, questions, or feature requests
• Submit a pull request for spec improvements or corrections
• Join the discussion in GitHub Discussions

Citing This Project

If you reference ccpkg in academic or technical writing, please cite it using GitHub's "Cite this repository" button or the BibTeX entry below (generated from CITATION.cff):

@software{allen_ccpkg_2026,
  author       = {Allen, Robert},
  title        = {ccpkg},
  version      = {0.0.4},
  date         = {2026-02-22},
  url          = {https://ccpkg.dev},
  license      = {CC-BY-4.0}
}

Acknowledgments

ccpkg builds on the following open standards:

Model Context Protocol. Model Context Protocol Specification. https://modelcontextprotocol.io/

Microsoft. Language Server Protocol. https://microsoft.github.io/language-server-protocol/

Agent Skills. Agent Skills Format. https://agentskills.io/

License

This specification is published under CC-BY-4.0.