SDK Interface

The AI•Pkg SDK has two public interfaces: the AI•Pkg.Core .NET library and the aipkg CLI. This spec defines the normative API surface for both. Anyone building a compatible tool, client, or alternative implementation should use this document as the reference.

AI•Pkg.Core

Cross-platform .NET 10 class library. Consumed by servers, CLI tools, and test harnesses.

aipkg CLI

Command-line tool. Single-file binary. No runtime required.

Part 1: `AI•Pkg.Core` Public API

Overview

Property	Value
Target framework	`net10.0`
NuGet package ID	`AI•Pkg.Core`
AOT compatible	Yes (no reflection emit, no dynamic code)
Serialization	`System.Text.Json` with source-generated serializers
Third-party NuGet deps	None

Public Types

AI•Pkg.Core (root)
AI•Pkg.Core.Packaging
AI•Pkg.Core.Platform
AI•Pkg.Core.Validation
AI•Pkg.Core.Versioning

// Represents a parsed .aispec manifest
public sealed class AipkgManifest
{
    public string Schema { get; init; }
    public string Id { get; init; }
    public string Version { get; init; }
    public string Description { get; init; }
    public IReadOnlyList<string> Authors { get; init; }
    public IReadOnlyList<string> Capabilities { get; init; }
    public IReadOnlyList<string> Targets { get; init; }
    public string? Title { get; init; }
    public string? Summary { get; init; }
    public string? ReleaseNotes { get; init; }
    public Uri? ProjectUrl { get; init; }
    public Uri? RepositoryUrl { get; init; }
    public string? RepositoryType { get; init; }
    public string? RepositoryBranch { get; init; }
    public string? RepositoryCommit { get; init; }
    public string? LicenseExpression { get; init; }
    public string? LicenseFile { get; init; }
    public string? IconFile { get; init; }
    public string? Readme { get; init; }
    public IReadOnlyList<string> Tags { get; init; }
    public string? Copyright { get; init; }
    public string? Language { get; init; }
    public ModelCompatibility? ModelCompatibility { get; init; }
    public IReadOnlyList<string> Permissions { get; init; }
    public IReadOnlyList<McpServerDefinition> McpServers { get; init; }
    public IReadOnlyList<PackageDependency> Dependencies { get; init; }
    public bool Listed { get; init; }
    public DeprecationInfo? Deprecated { get; init; }
}

public sealed class ModelCompatibility
{
    public int? MinimumContextWindow { get; init; }
    public bool? RequiresToolUse { get; init; }
    public bool? RequiresVision { get; init; }
    public string? Notes { get; init; }
}

public sealed class McpServerDefinition
{
    public string Name { get; init; }
    public string Transport { get; init; }
    public string? Command { get; init; }
    public IReadOnlyList<string> Args { get; init; }
    public Uri? Url { get; init; }
    public IReadOnlyDictionary<string, string> Env { get; init; }
    public string? Description { get; init; }
    public IReadOnlyList<string> Targets { get; init; }
}

public sealed class PackageDependency
{
    public string Id { get; init; }
    public string Version { get; init; }
    public IReadOnlyList<string> Apms { get; init; }
    public bool Optional { get; init; }
}

public sealed class DeprecationInfo
{
    public string? Message { get; init; }
    public string? AlternatePackageId { get; init; }
    public string? AlternatePackageVersion { get; init; }
}

// Reads .aipkg archives
public sealed class AipkgReader : IDisposable
{
    public AipkgReader(Stream stream);
    public AipkgReader(string filePath);

    // Reads the manifest without extracting the full archive
    public AipkgManifest ReadManifest();

    // Lists all entries in the archive
    public IReadOnlyList<AipkgEntry> GetEntries();

    // Opens a specific entry for reading
    public Stream OpenEntry(string entryPath);

    // Extracts files for a given APM, applying fallback resolution
    public IReadOnlyDictionary<string, Stream> ExtractForPlatform(string apmMoniker);
}

public sealed record AipkgEntry(
    string Path,
    long CompressedSize,
    long UncompressedSize,
    string Section  // "shared", "apm/{moniker}", "root", "reserved"
);

// Creates .aipkg archives
public sealed class AipkgWriter : IDisposable
{
    public AipkgWriter(Stream outputStream);
    public AipkgWriter(string outputFilePath);

    // Must be called first
    public void WriteManifest(AipkgManifest manifest);

    // Adds a file to shared/
    public void AddSharedFile(string relativePath, Stream content);

    // Adds a file to apm/{moniker}/
    public void AddPlatformFile(string moniker, string relativePath, Stream content);

    // Adds icon, README, LICENSE at archive root
    public void AddRootFile(string filename, Stream content);

    public void Finalize();
}

public sealed class PlatformCompatibilityService
{
    // e.g. "claude-code" → ["apm/claude-code", "apm/claude", "apm/ai", "shared"]
    public IReadOnlyList<string> GetFallbackChain(string moniker);

    public string? GetParent(string moniker);

    public bool IsCompatible(IReadOnlyList<string> packageTargets, string targetMoniker);

    public string? GetInstallPath(string moniker, OperatingSystem os);

    public IReadOnlyList<ApmInfo> GetAllPlatforms();

    public bool IsKnown(string moniker);
}

public sealed record ApmInfo(
    string Moniker,
    string DisplayName,
    string? Parent,
    string? InstallPath,
    string Stability  // "stable", "provisional", "deprecated"
);

public sealed class AipkgValidator
{
    public ValidationResult ValidateManifest(AipkgManifest manifest);
    public ValidationResult ValidateArchive(Stream archiveStream);
}

public sealed class ValidationResult
{
    public bool IsValid { get; }
    public IReadOnlyList<ValidationError> Errors { get; }
    public IReadOnlyList<ValidationWarning> Warnings { get; }
}

public sealed record ValidationError(string Code, string Message, string? Field = null);
public sealed record ValidationWarning(string Code, string Message, string? Field = null);

// SemVer 2.0.0 — compatible with NuGet versioning
public sealed class AipkgVersion : IComparable<AipkgVersion>
{
    public static AipkgVersion Parse(string version);
    public static bool TryParse(string version, out AipkgVersion result);
    public bool SatisfiesRange(string versionRange);
}

100% of public surface members must carry XML doc comments before the 1.0.0 release.

Part 2: `aipkg` CLI Command Reference

Command Reference

aipkg pack

aipkg pack [manifest-path] [options]

Arguments:
  manifest-path    Path to .aispec file (default: finds *.aispec in current dir)

Options:
  -o, --output <dir>     Output directory (default: current dir)
  --no-validate          Skip validation (not recommended)
  -v, --verbosity <lvl>  Verbosity: quiet, normal, detailed (default: normal)

Output:
  {id}.{version}.aipkg

Behavior:

Reads and validates the .aispec manifest
Resolves all file references (icon, readme, license, shared/, apm/)
Builds the ZIP archive
Reports the archive size and file count

aipkg push

aipkg push <package-path> [options]

Arguments:
  package-path    Path to .aipkg file

Options:
  -s, --source <url>    Registry URL (default: https://aipkg.org)
  -k, --api-key <key>   API key (or set AIPKG_API_KEY env var)
  --skip-duplicate      Return success if version already exists
  -t, --timeout <sec>   Upload timeout in seconds (default: 300)

aipkg install

aipkg install <id[@version]> [options]
aipkg install                    ← installs from aipkg.config.json

Options:
  -p, --platform <apm>    Target APM moniker (default: auto-detect)
  -g, --global            Install globally (not project-scoped)
  --prerelease            Include pre-release versions
  -s, --source <url>      Registry URL
  --dry-run               Show what would be installed without installing

Auto-detect platform: the CLI inspects the current directory for known config directories (.claude/, .cursor/, etc.) to infer the active platform. Falls back to prompting if ambiguous.

aipkg restore

aipkg restore [options]

Options:
  --locked    Fail if aipkg.lock.json is out of date
  --no-lock   Do not write/update aipkg.lock.json
  --force     Re-install even if already installed

Reads aipkg.config.json and installs all declared packages.

aipkg remove

aipkg remove <id> [options]

Options:
  -p, --platform <apm>    Target APM moniker
  -g, --global            Remove globally installed package

aipkg list

aipkg list [options]

Options:
  -p, --platform <apm>    Filter by platform
  -g, --global            List global packages
  --format <fmt>          Output format: table, json (default: table)

aipkg search

aipkg search <query> [options]

Options:
  --apm <moniker>         Filter by platform
  --capability <cap>      Filter by capability
  --prerelease            Include pre-release versions
  --take <n>              Results to show (default: 20, max: 100)
  --format <fmt>          Output format: table, json (default: table)

aipkg info

aipkg info <id[@version]> [options]

Options:
  --format <fmt>    Output format: text, json (default: text)
  -s, --source      Registry URL

Shows: ID, version, description, authors, capabilities, targets, permissions, dependencies, download count.

aipkg verify

aipkg verify <package-path>

Validates:
  - Archive integrity (ZIP validity)
  - Manifest schema (JSON Schema)
  - Manifest business rules (see Metadata Schema spec)
  - File structure conventions
  - Icon dimensions and format
  - Size limits

Exit codes: 0 = valid, 1 = invalid, 2 = warnings only

aipkg sources

aipkg sources list
aipkg sources add <name> <url>
aipkg sources remove <name>
aipkg sources update <name> [--url <url>]

Sources are stored in ~/.aipkg/sources.json.

aipkg new

aipkg new [options]

Options:
  --id <id>           Package ID (prompted if not given)
  --capability <cap>  Initial capability
  --non-interactive   Use defaults without prompting

Creates a minimal {id}.aispec file in the current directory.

Part 3: Configuration File Schemas

aipkg.config.json
aipkg.lock.json
~/.aipkg/config.json

Project dependencies file — analogous to package.json (npm).

{
  "$schema": "https://aipkg.org/schemas/config/1.0.0",
  "platform": "claude-code",
  "packages": [
    { "id": "git-helpers", "version": "1.0.0" },
    { "id": "filesystem-mcp", "version": "2.1.0", "optional": true }
  ],
  "sources": [
    { "name": "aipkg.org", "url": "https://aipkg.org/v3/index.json" }
  ]
}

Lockfile — analogous to package-lock.json. Records exact resolved versions and content hashes.

{
  "$schema": "https://aipkg.org/schemas/lock/1.0.0",
  "version": 1,
  "platform": "claude-code",
  "packages": [
    {
      "id": "git-helpers",
      "resolved": "1.0.0",
      "contentHash": "sha256:abc123...",
      "downloadUrl": "https://aipkg.org/v3/flatcontainer/git-helpers/1.0.0/git-helpers.1.0.0.aipkg",
      "installedFiles": [
        ".claude/skills/git-helpers.md",
        ".claude/prompts/git-base.md"
      ],
      "dependencies": []
    }
  ]
}

Global user settings:

{
  "defaultSource": "https://aipkg.org/v3/index.json",
  "defaultPlatform": "claude-code",
  "globalInstallPath": "~/.aipkg/global/",
  "httpTimeout": 300
}

Part 4: TypeScript SDK Interface (Post-MVP)

The TypeScript SDK packages provide registry client and manifest parsing functionality:

Package	Purpose
`@aipkg/core`	Registry client, manifest parsing, version resolution
`@aipkg/claude-code`	Claude Code integration helpers
`@aipkg/copilot`	GitHub Copilot integration helpers
`@aipkg/cursor`	Cursor integration helpers

// Registry client
class AipkgClient {
  constructor(options?: { source?: string });
  search(query: string, options?: SearchOptions): Promise<SearchResult>;
  getPackage(id: string, version?: string): Promise<PackageMetadata>;
  getVersions(id: string): Promise<string[]>;
  download(id: string, version: string): Promise<Uint8Array>;
}

// Manifest parsing
function parseManifest(json: string): AipkgManifest;
function validateManifest(manifest: AipkgManifest): ValidationResult;

type Capability = 'skill' | 'command' | 'agent' | 'prompt' | 'mcp-server' | 'config' | 'hook' | 'theme';

TypeScript SDK is not in scope for MVP. Defined here for future reference.

Getting Started

Specifications

Implementation Plan

Legacy (NuGetGallery)

Specs

SDK Interface

AI•Pkg.Core

aipkg CLI

Part 1: `AI•Pkg.Core` Public API

Overview

Public Types

Part 2: `aipkg` CLI Command Reference

Command Reference

Part 3: Configuration File Schemas

Part 4: TypeScript SDK Interface (Post-MVP)

AI•Pkg.Core

aipkg CLI

​Part 1: AI•Pkg.Core Public API

​Overview

​Public Types

​Part 2: aipkg CLI Command Reference

​Command Reference

​Part 3: Configuration File Schemas

​Part 4: TypeScript SDK Interface (Post-MVP)

Part 1: `AI•Pkg.Core` Public API

Overview

Public Types

Part 2: `aipkg` CLI Command Reference

Command Reference

Part 3: Configuration File Schemas

Part 4: TypeScript SDK Interface (Post-MVP)