Introducing ccpkg: A Universal Packaging Format for AI Coding Assistant Extensions

[zircote]

Introducing ccpkg: A Cross-Tool Packaging Format for AI Coding Assistant Extensions

Hey everyone,

I wanted to share a project I've been working on and get feedback while the spec is still in draft.

The Problem

If you use more than one AI coding assistant (Claude Code, GitHub Copilot, Gemini CLI, Codex, OpenCode), you've probably noticed that each tool has its own way of handling extensions. Skills go in one directory, MCP servers get configured in a different JSON file, hooks wire up differently, and instruction files have different names. A useful skill you built for Claude Code doesn't just work in Gemini CLI without manual porting.

Fragmentation aside, the current setup has other problems:

• Extensions installed from Git repos break silently without version pinning or integrity checks
• Session startup slows down as each plugin fetches state from remote sources
• No trust signals -- discovery is word-of-mouth with no curation, verification, or structured metadata
• Configuration is scattered -- MCP servers, secrets, environment variables, and auth tokens end up in opaque config files across the filesystem

What ccpkg Is

ccpkg is a packaging format -- a self-contained ZIP archive (.ccpkg) that bundles skills, agents, commands, hooks, MCP servers, LSP servers, and instructions into one archive.

A package looks like this:

example-plugin-1.0.0.ccpkg (ZIP)
+-- manifest.json           # Package identity, components, config
+-- skills/                 # SKILL.md files
+-- agents/                 # AGENT.md files
+-- commands/               # Slash command definitions
+-- hooks/                  # Event handlers
+-- mcp/                    # MCP server config template
+-- instructions/           # Instruction file content
+-- LICENSE

Installation is deterministic: extract, configure, register. No post-install scripts, no network fetches, no build steps.

How Cross-Tool Portability Works

Each AI coding assistant gets an adoption specification -- a JSON document that maps the ccpkg format to host-specific conventions. It tells the installer where each component type goes on disk, how hook events translate between the canonical names and the host's names, which instruction filename the assistant expects, and how extensions register themselves.

When you install a ccpkg package, the installer reads the adoption spec for your assistant, places everything in the right location, translates event names, and wires up configuration. The package author writes one manifest and the adoption spec handles the rest.

We currently have adoption specs for five assistants:

Assistant	Config Dir	Instruction File	Hook Events
Claude Code	~/.claude	CLAUDE.md	17 events, 3 execution models
GitHub Copilot CLI	~/.copilot	.github/copilot-instructions.md	6 events
Codex CLI	~/.codex	AGENTS.md	1 event (more planned)
Gemini CLI	~/.gemini	GEMINI.md	11 events
OpenCode	~/.config/opencode	AGENTS.md	24+ events

Design Decisions

Some decisions worth calling out:

1. Self-contained archives: all dependencies vendored, no runtime network fetches
2. Tool-agnostic core with thin tool-specific adapters (the adoption specs)
3. Deterministic installation means same inputs produce identical output, always
4. No central registry required -- packages can live on any URL, GitHub release, or S3 bucket
5. No install-time code execution. Purely declarative; configuration is separated from code
6. MCP server deduplication: when multiple packages ship the same MCP server, highest compatible version wins
7. Lazy loading -- only metadata loads at startup; 20 packages should have the same startup cost as zero

What Exists Today

This is a developing specification, not production software. Here's what's in the repo right now:

• The core ccpkg specification covering archive structure, manifest schema, install/uninstall lifecycle, lockfiles, and registries
• The assistant adoption specification defining how adoption specs work
• Five adoption spec profiles (Claude Code, Copilot CLI, Codex CLI, Gemini CLI, OpenCode)
• JSON Schema validation for both the core manifest and adoption specs
• A documentation site built with Astro Starlight at ccpkg.dev

There is no CLI installer yet. The spec is intentionally being written first so that any implementation (official or community-built) has a solid, validated contract to build against.

What I'm Looking For

Feedback. Specifically:

• Does the problem resonate? Are you maintaining extensions across multiple assistants and running into these problems?
• Are the adoption specs covering the right surface area? Each one maps component paths, hook events, instruction formats, and configuration locations. What's missing?
• Should the spec handle anything else? Things like themes, keybindings, or UI extensions are intentionally out of scope right now, but I want to know what you'd actually use.
• Would you contribute an adoption spec? If you use an assistant that isn't covered yet (Cursor, Windsurf, Aider, etc.), the format is documented and straightforward to author.

Links

• Repository: https://github.com/zircote/ccpkg
• Documentation: https://ccpkg.dev
• Schema: https://ccpkg.dev/schemas/assistant-adoption.schema.json
• License: CC-BY-4.0 (specification), MIT (tooling)

This is early-stage work and everything is open to change. If cross-tool extension packaging sounds useful, I'd appreciate your thoughts.