Portability

Cross-Tool Portability

ccpkg achieves cross-tool portability by building on universal open standards and providing thin adapter mappings for tool-specific conventions.

Universal Components

The following components are tool-agnostic and work across any host that supports the underlying standard:

Component	Standard
Skills (SKILL.md)	Agent Skills
MCP servers (.mcp.json)	Model Context Protocol
LSP servers (.lsp.json)	Language Server Protocol
Config schema	JSON Schema

Component Portability Matrix

The portability status of each component type is documented in each host’s adoption specification under component_support. Consult the relevant adoption spec to determine which components a host supports and at what level.

Support levels:

• Native: Component type is natively supported by the host
• Via adapter: Component concept maps to a different host mechanism (adapter needed)
• Experimental: Host support exists but is not yet stable
• Not supported: Host has no equivalent; component is silently skipped
• Deprecated: Host support exists but is scheduled for removal

Package authors SHOULD use per-component host scoping (see Components Object) to include host-specific variants of components. Authors SHOULD NOT assume all hosts support all component types.

Tool-Specific Adapters

Four mechanisms handle tool-specific differences:

1. Instruction file assembly. Base + per-host overlay assembly via components.instructions, with output written to the host-specific filename from targets.*.instructions_file. See Instructions.

2. Targets object. Per-host overrides in manifest.json. See Targets Object.

3. Hooks. Hosts MUST silently ignore unrecognized event types, enabling packages to include hooks for multiple hosts without conflict.

4. Per-component host scoping. The hosts field in structured component declarations limits a component to specific hosts. Installers silently skip non-matching components.

Portability Guidelines for Authors

• Use instructions.base with per-host overlays. Do not hardcode tool-specific filenames.
• Prefer MCP for tool integration over host-specific mechanisms.
• Use compatibility to declare minimum host versions rather than excluding hosts.
• Use per-component hosts scoping for host-specific hooks or agents alongside universal skills.
• Use canonical event names for hook portability. Consult each host’s adoption specification for supported events.
• Scope agents to specific hosts via hosts — agent formats are not yet portable across hosts.
• Scope LSP components to hosts that support them. Check each host’s component_support.lsp_servers in its adoption spec.
• When a host requires an MCP environment variable prefix, declare it via targets.{host}.mcp_env_prefix. See the host’s adoption spec for the specific prefix value.
• Test packages across multiple hosts when possible.