llms.txt

# ccpkg - AI Coding Assistant Extension Packaging Format

## Documentation Index

- [Home](https://ccpkg.dev/)
- [Specification](https://ccpkg.dev/spec/specification.html)
- [Design Document](https://ccpkg.dev/docs/plans/2026-02-14-ccpkg-design.html)
- [Manifest JSON Schema](https://ccpkg.dev/spec/schemas/manifest.schema.json)
- [GitHub Repository](https://github.com/zircote/ccpkg)

## Overview

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 into a single
portable unit.

The format is built on open standards: Agent Skills (SKILL.md),
Model Context Protocol (MCP), Language Server Protocol (LSP),
Semantic Versioning, and JSON Schema.

## Key Concepts

- Self-contained ZIP archives (.ccpkg) with no post-install steps
- Declarative manifest.json with typed configuration
- Universal core + thin tool-specific adapters
- Lazy loading for fast startup (metadata only at session start)
- No central registry required (decentralized JSON registries)
- No install-time code execution
- Deterministic lockfiles (ccpkg-lock.json) with SHA-256 checksums
- Install scope: user (~/.claude/packages/) or project (<project>/.claude/packages/)

## Component Types

Packages may contain any combination of:
- Skills (SKILL.md, Agent Skills format)
- Agents (AGENT.md)
- Commands (slash commands, namespaced as /package-name:command-name)
- Hooks (event handlers: PreToolUse, PostToolUse, SessionStart, SessionStop)
- MCP servers (three modes: traditional, embedded mcpb, referenced mcpb)
- LSP servers
- Instructions (INSTRUCTIONS.md with tool-specific filename mappings)

## Configuration Model

Manifest declares typed config slots: secret, string, number,
boolean, enum, path. Values collected at install time. Templates
(.mcp.json, .lsp.json) use ${config.VARIABLE_NAME} substitution.
Secrets masked in logs, excluded from lockfiles.

## Cross-Tool Portability

Works across Claude Code, Gemini CLI, Codex, GitHub Copilot, and
other tools that support MCP, LSP, or Agent Skills. Tool-specific
differences handled via instructions/mappings.json and the targets
manifest field.

## Specification Version

Current draft: 2026-02-14. Uses RFC 2119 conventions (MUST, SHOULD, MAY).