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

# AI•Pkg Specification Suite

> Normative specifications for the AI•Pkg package format, platform targeting system, registry protocol, and SDK interface — everything needed to build a compatible tool or registry implementation.

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

<CardGroup cols={2}>
  <Card title="01 · Package Format" icon="box-archive" href="01-aipkg-format">
    `.aipkg` archive format, manifest naming, directory layout, conflict resolution, size limits.
  </Card>

  <Card title="02 · Package Naming" icon="tag" href="02-package-naming">
    ID syntax rules, forbidden patterns, reserved IDs, publisher scoping conventions.
  </Card>

  <Card title="03 · Versioning" icon="git-branch" href="03-versioning">
    SemVer 2.0.0 compliance, pre-release, normalization, dependency ranges, immutability.
  </Card>

  <Card title="04 · Prefix Reservations" icon="shield-check" href="04-prefix-reservations">
    Exclusive prefix ownership for verified publishers, badge display, transfer policy.
  </Card>

  <Card title="05 · Code Signing" icon="shield" href="05-code-signing">
    Signing algorithm, PKCS#7/CMS format, trust anchors, verification procedure, timestamping.
  </Card>
</CardGroup>

### Platform Targeting

<CardGroup cols={2}>
  <Card title="06 · Platform Targeting" icon="sitemap" href="06-platform-targeting">
    AI Platform Moniker (APM) system, canonical table, fallback graph, compatibility rules.
  </Card>

  <Card title="07 · Platform Versioning" icon="git-merge" href="07-platform-versioning">
    Versioned APM monikers, breaking change policy, fallback behavior, publisher guidance.
  </Card>
</CardGroup>

### Package Content

<CardGroup cols={1}>
  <Card title="08 · Metadata Schema" icon="file-code" href="08-metadata-schema">
    Full `.aispec` JSON Schema, field reference, capability and permission enums, examples.
  </Card>
</CardGroup>

### Registry Protocol

<CardGroup cols={3}>
  <Card title="09 · Registry API" icon="server" href="09-registry-api">
    All registry endpoints — service index, registration, search, push, platform list.
  </Card>

  <Card title="10 · SDK Interface" icon="terminal" href="10-sdk-interface">
    `AI•Pkg.Core` public API types, `aipkg` CLI command syntax, config file schemas.
  </Card>

  <Card title="11 · Registry UI" icon="display" href="11-registry-ui">
    URL inventory, rendering requirements, performance targets, accessibility, SEO.
  </Card>
</CardGroup>

### Security

<CardGroup cols={1}>
  <Card title="12 · Package Security" icon="shield-halved" href="12-security">
    Multi-layer security model — static analysis, AV scanning, AI-powered prompt injection detection, signature enforcement, immutability guarantees, and incident response.
  </Card>
</CardGroup>

***

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

1. **APM-first design** — Every package operation is aware of platform targeting. The fallback graph ensures packages work across platform versions without requiring republication.
2. **`.aispec` is JSON** — Not XML. The `{id}.aispec` naming mirrors `.nuspec` and `.csproj` conventions.
3. **Forward compatibility** — Unknown APM monikers are silently skipped, never errors. No moniker is ever deleted from the canonical table.
4. **Immutable versions** — Published versions cannot be overwritten. Unlisting is the only mechanism to hide a version.
5. **Normative API-first** — Every registry behavior is defined by its API contract, not by server implementation details.
6. **AOT-capable SDK** — `AI•Pkg.Core` is AOT-compatible; no dynamic code. The `aipkg` CLI ships as a single native binary.
7. **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:

* [ ] Someone to implement a `.aipkg` parser from spec alone (→ [spec 01](01-aipkg-format))
* [ ] Someone to implement package ID validation (→ [spec 02](02-package-naming))
* [ ] Someone to implement version parsing and range resolution (→ [spec 03](03-versioning))
* [ ] Someone to implement APM resolution and install path logic (→ [spec 06](06-platform-targeting))
* [ ] Someone to handle platform evolution correctly (→ [spec 07](07-platform-versioning))
* [ ] Someone to write a JSON Schema validator for `.aispec` (→ [spec 08](08-metadata-schema))
* [ ] Someone to implement every registry endpoint with correct request/response shapes (→ [spec 09](09-registry-api))
* [ ] Someone to implement `AI•Pkg.Core` public API (→ [spec 10](10-sdk-interface))
* [ ] Someone to build a compatible registry web UI (→ [spec 11](11-registry-ui))
* [ ] Someone to implement the full security scanning pipeline (→ [spec 12](12-security))