AI•Pkg Specification Suite

AI•Pkg packages AI skills, commands, MCP server configurations, system prompts, and other plugin assets that work across multiple AI platforms (Claude Code, GitHub Copilot, Cursor, Windsurf, OpenCode, and more). This specification suite is addressed to third-party implementers: tool authors, alternative registry operators, package authors, and anyone building compatible tooling. It contains no implementation-specific language.

Spec Index

Package Identity

01 · Package Format

.aipkg archive format, manifest naming, directory layout, conflict resolution, size limits.

02 · Package Naming

ID syntax rules, forbidden patterns, reserved IDs, publisher scoping conventions.

03 · Versioning

SemVer 2.0.0 compliance, pre-release, normalization, dependency ranges, immutability.

04 · Prefix Reservations

Exclusive prefix ownership for verified publishers, badge display, transfer policy.

05 · Code Signing

Signing algorithm, PKCS#7/CMS format, trust anchors, verification procedure, timestamping.

Platform Targeting

06 · Platform Targeting

AI Platform Moniker (APM) system, canonical table, fallback graph, compatibility rules.

07 · Platform Versioning

Versioned APM monikers, breaking change policy, fallback behavior, publisher guidance.

Package Content

08 · Metadata Schema

Full .aispec JSON Schema, field reference, capability and permission enums, examples.

Registry Protocol

09 · Registry API

All registry endpoints — service index, registration, search, push, platform list.

10 · SDK Interface

AI•Pkg.Core public API types, aipkg CLI command syntax, config file schemas.

11 · Registry UI

URL inventory, rendering requirements, performance targets, accessibility, SEO.

Security

12 · Package Security

Multi-layer security model — static analysis, AV scanning, AI-powered prompt injection detection, signature enforcement, immutability guarantees, and incident response.

Conceptual Model

AI•Pkg maps directly onto the NuGet conceptual model:

NuGet	AI•Pkg	Notes
`.nupkg`	`.aipkg`	ZIP archive, same mechanism
`.nuspec`	`{id}.aispec`	JSON instead of XML; named after the package ID
Target Framework Moniker (TFM)	AI Platform Moniker (APM)	e.g., `claude-code`, `copilot`, `cursor`
`lib/{tfm}/`	`apm/{moniker}/`	Platform-specific assets
`contentFiles/`	`shared/`	Platform-agnostic assets
Package Type	Capabilities	`mcp-server`, `skill`, `command`, `agent`, `prompt`, `config`
`NuGet.org`	`AI•Pkg.org`	Registry

Key Principles

APM-first design — Every package operation is aware of platform targeting. The fallback graph ensures packages work across platform versions without requiring republication.
.aispec is JSON — Not XML. The {id}.aispec naming mirrors .nuspec and .csproj conventions.
Forward compatibility — Unknown APM monikers are silently skipped, never errors. No moniker is ever deleted from the canonical table.
Immutable versions — Published versions cannot be overwritten. Unlisting is the only mechanism to hide a version.
Normative API-first — Every registry behavior is defined by its API contract, not by server implementation details.
AOT-capable SDK — AI•Pkg.Core is AOT-compatible; no dynamic code. The aipkg CLI ships as a single native binary.
Defense in depth — Security is layered: static analysis, AV scanning, AI content audit, cryptographic signing, and runtime anomaly detection. No single layer is the sole gate.

Verification Checklist

A complete spec suite must allow:

01 · Package FormatThe `.aipkg` archive format, manifest naming convention, directory layout, file conflict resolution, size limits, and relationship to NuGet's `.nupkg`.

⌘I

Documentation Index

​Spec Index

​Package Identity