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:
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). .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/ 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.) |
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 matchlib/{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 typespackage/ — 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:
Use this when serving packages over HTTP.
Creation and Extraction
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.
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.