> ## Documentation Index
> Fetch the complete documentation index at: https://aipkg.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Package Format

> The `.aipkg` archive format, manifest naming convention, directory layout, file conflict resolution, size limits, and relationship to NuGet's `.nupkg`.

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.

<Note>
  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)](08-metadata-schema).
</Note>

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`.

<Note>
  Valid moniker directory names are the canonical APM names defined in [Platform Targeting (spec 06)](06-platform-targeting). Unknown monikers are silently ignored by the runtime.
</Note>

### `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):

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

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

<Tip>
  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`.
</Tip>

***

## 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   |

<Warning>
  Archives exceeding these limits are rejected during `push` with a `413` response.
</Warning>

***

## 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)](05-code-signing) 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

<Tabs>
  <Tab title="aipkg pack">
    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)](10-sdk-interface) for full CLI details.
  </Tab>

  <Tab title="aipkg install">
    The `aipkg install` command follows these steps:

    <Steps>
      <Step title="Download">
        Downloads or reads a `.aipkg` archive.
      </Step>

      <Step title="Read manifest">
        Reads the `.aispec` manifest.
      </Step>

      <Step title="Determine APM">
        Determines the target APM from CLI arg, project config, or auto-detection.
      </Step>

      <Step title="Resolve fallback chain">
        Resolves the fallback chain for the APM. See [Platform Targeting (spec 06)](06-platform-targeting).
      </Step>

      <Step title="Collect baseline">
        Collects files from `lib/shared/` as the baseline.
      </Step>

      <Step title="Apply overlays">
        Overlays files from each `lib/{moniker}/` directory in the fallback chain, highest specificity last (most specific wins).
      </Step>

      <Step title="Deploy content">
        Deploys the resolved file set to the platform's install path via the runtime.
      </Step>

      <Step title="Update lockfile">
        Updates `aipkg.lock.json`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## 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) |

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