Package Format

An .aipkg file is a ZIP archive (deflate or store compression) with a structured directory layout. The format is mechanically identical to .nupkg — any ZIP tool can read it — but the contents and naming conventions differ. Files on disk follow the naming convention:

{id}.{version}.aipkg

Example: my-mcp-server.1.2.0.aipkg

Archive Structure

{id}.{version}.aipkg
├── {id}.aispec                  # Required. Package manifest (JSON).
├── README.md                    # Optional. Embedded readme shown on registry.
├── LICENSE.txt                  # Optional. License text.
├── lib/                         # Optional. AI content (skills, commands, MCP configs, etc.).
│   ├── shared/                  # Files installed on all platforms (universal baseline).
│   │   ├── skills/
│   │   │   └── my-skill.md
│   │   ├── commands/
│   │   │   └── my-command.md
│   │   ├── agents/
│   │   │   └── my-agent.md
│   │   ├── prompts/
│   │   │   └── system-prompt.md
│   │   ├── hooks/
│   │   │   └── pre-tool-use.md
│   │   ├── mcp/
│   │   │   └── server-config.json
│   │   └── lsp/
│   │       └── lsp-config.json
│   ├── claude-code/             # Files for Claude Code only (overrides lib/shared/).
│   │   └── skills/
│   │       └── my-skill.md     # Overrides lib/shared/skills/my-skill.md on claude-code.
│   ├── claude/                  # Files for all claude/* platforms.
│   └── copilot/                 # Files for all copilot/* platforms.
├── tools/                       # Optional. Executables (MCP server binaries, helper tools).
│   ├── win-x64/
│   │   └── my-mcp-server.exe
│   ├── win-arm64/
│   │   └── my-mcp-server.exe
│   ├── osx-x64/
│   │   └── my-mcp-server
│   ├── osx-arm64/
│   │   └── my-mcp-server
│   ├── linux-x64/
│   │   └── my-mcp-server
│   ├── linux-arm64/
│   │   └── my-mcp-server
│   ├── linux-musl-x64/          # Alpine / containerized Linux.
│   │   └── my-mcp-server
│   └── any/                     # Platform-agnostic scripts or JARs.
│       └── my-tool.sh
├── images/                      # Optional. Visual assets for registry display.
│   ├── icon.png                 # Square PNG, ≥128×128. Shown on registry.
│   └── (images referenced in README.md)
└── _rels/                       # Reserved. Do not use in user packages.
    └── .rels                    # Optional Open Packaging Conventions relationship file.

Manifest File: `{id}.aispec`

The manifest is a JSON file stored at the root of the archive.

The manifest must be named exactly {id}.aispec where {id} matches the id field inside the manifest, be valid UTF-8 with no BOM, and conform to the schema defined in Metadata Schema (spec 08).

The .aispec extension was chosen to mirror NuGet’s .nuspec and the .csproj naming pattern — the filename is self-identifying in a repository or file listing. Inside the archive, globbing for *.aispec reliably locates the manifest.

Directory Conventions

`lib/`

The lib/ folder is the primary content container. It holds all AI content the runtime deploys to the target platform. The runtime reads the manifest and lib/ together — it does not simply unzip files, but interprets content declarations and installs assets to the correct platform locations.

`lib/shared/`

Files in lib/shared/ are the universal baseline — installed on all platforms unless overridden by a platform-specific directory. There are no mandatory subdirectory names, but the following are conventional:

Subdirectory	Contents
`skills/`	Skill definition files (`.md` or platform-specific format)
`commands/`	Slash command definition files
`agents/`	Agent definition files
`prompts/`	System prompt and prompt template files
`hooks/`	Hook event handlers, keyed by event name
`mcp/`	MCP server configuration files (JSON)
`lsp/`	LSP server configuration files
`config/`	Generic configuration files

`lib/{moniker}/`

Files in lib/{moniker}/ apply only to the named platform (and its children in the APM fallback hierarchy). The same subdirectory conventions from lib/shared/ apply. A file at lib/claude-code/skills/my-skill.md overrides lib/shared/skills/my-skill.md when installing for claude-code.

Valid moniker directory names are the canonical APM names defined in Platform Targeting (spec 06). Unknown monikers are silently ignored by the runtime.

`tools/`

The tools/ folder contains executable binaries (MCP server executables, helper tools, scripts). The runtime extracts and registers these based on the host OS and architecture. Subdirectory names follow .NET RID conventions:

Subdirectory	Platform
`win-x64/`	Windows x64
`win-arm64/`	Windows ARM64
`osx-x64/`	macOS x64
`osx-arm64/`	macOS ARM64 (Apple Silicon)
`linux-x64/`	Linux x64
`linux-arm64/`	Linux ARM64
`linux-musl-x64/`	Alpine / musl-based Linux x64
`any/`	Platform-agnostic (scripts, JARs, etc.)

The runtime selects the most specific matching subdirectory for the current host. If no exact match is found, any/ is used as a fallback.

`images/`

The images/ folder holds visual assets used by the registry and package documentation. No subdirectory structure is required.

File	Purpose
`icon.png`	Package icon. Square PNG, ≥128×128. Referenced in `.aispec` via `iconPath`.
Any `.png`, `.jpg`, `.svg`, `.webp`	Images embedded in `README.md` via relative paths.

File Conflict Resolution

When the same relative path exists in multiple lib/ subdirectories, the most platform-specific file wins. Resolution order within lib/ (highest priority first):

lib/{exact-moniker}/ — most specific platform match
lib/{parent-moniker}/ — parent in fallback graph (e.g., lib/claude/ when installing for claude-code)
lib/shared/ — universal baseline

If the same relative path appears at multiple specificity levels, only the highest-priority copy is installed.

For a claude-code install, lib/claude-code/skills/demo.md takes precedence over lib/claude/skills/demo.md, which takes precedence over lib/shared/skills/demo.md.

Compression

The .aispec manifest file must be stored uncompressed (deflate level 0 / store method) to allow streaming reads without full archive extraction.
All other files may use deflate compression (level 1–9). Level 6 is recommended.
ZIP64 is supported and required when any single file exceeds 4 GB or the total archive exceeds 4 GB.

Size Limits

Constraint	Limit
Total archive size	512 MB
Single file within archive	256 MB
Manifest file (`.aispec`)	1 MB
`icon.png`	1 MB
`README.md`	5 MB

Archives exceeding these limits are rejected during push with a 413 response.

Reserved Paths

The following paths inside the archive are reserved and must not be created by package authors:

_rels/ — Open Packaging Conventions relationships
[Content_Types].xml — OPC content types
package/ — Reserved for future use
.signature.p7s — Reserved for future package signing

Signing

See Code Signing (spec 05) for the normative signing specification. The .signature.p7s path is reserved in all archives; the signing algorithm, trust model, and verification procedure are defined in that document.

MIME Type

The registered MIME type for .aipkg files is:

application/x-aipkg

Use this when serving packages over HTTP.

Creation and Extraction

aipkg pack
aipkg install

The aipkg pack command reads an .aispec file from the current directory (or a specified path), validates it, collects referenced files, and produces a {id}.{version}.aipkg archive.See SDK Interface (spec 10) for full CLI details.

The aipkg install command follows these steps:

Download

Downloads or reads a .aipkg archive.

Read manifest

Reads the .aispec manifest.

Determine APM

Determines the target APM from CLI arg, project config, or auto-detection.

Resolve fallback chain

Resolves the fallback chain for the APM. See Platform Targeting (spec 06).

Collect baseline

Collects files from lib/shared/ as the baseline.

Apply overlays

Overlays files from each lib/{moniker}/ directory in the fallback chain, highest specificity last (most specific wins).

Deploy content

Deploys the resolved file set to the platform’s install path via the runtime.

Update lockfile

Updates aipkg.lock.json.

Relationship to NuGet `.nupkg`

.aipkg is intentionally isomorphic with .nupkg:

Aspect	`.nupkg`	`.aipkg`
Container format	ZIP	ZIP
Manifest	`{id}.nuspec` (XML)	`{id}.aispec` (JSON)
Platform-targeted content	`lib/{tfm}/`	`lib/{moniker}/`
Universal baseline	`lib/netstandard2.0/` (by convention)	`lib/shared/`
Executables	`tools/`	`tools/{rid}/`
Visual assets	`images/`	`images/`
Compression	deflate	deflate
Signing	`.signature.p7s`	`.signature.p7s` (reserved)

This similarity is deliberate: existing NuGet tooling infrastructure (CDN, storage, streaming readers) requires minimal adaptation to serve .aipkg files.

Documentation Index

​Archive Structure

​Manifest File: {id}.aispec

​Directory Conventions

​lib/

​lib/shared/

​lib/{moniker}/

​tools/

​images/

​File Conflict Resolution

​Compression

​Size Limits

​Reserved Paths

​Signing

​MIME Type

​Creation and Extraction

​Relationship to NuGet .nupkg

Archive Structure

Manifest File: `{id}.aispec`

Directory Conventions

`lib/`

`lib/shared/`

`lib/{moniker}/`

`tools/`

`images/`

File Conflict Resolution

Compression

Size Limits

Reserved Paths

Signing

MIME Type

Creation and Extraction

Relationship to NuGet `.nupkg`