Skip to main content
Every AI•Pkg package has an ID — a globally unique, immutable string that identifies the package across all versions. This document defines the normative rules for package IDs and display names.

​
Package ID Syntax

A package ID must conform to the following rules:
  • Pattern: ^[a-z][a-z0-9\-\.]{0,127}$
  • Max length: 128 characters
  • First character: lowercase ASCII letter (a–z)
  • Remaining characters: lowercase ASCII letters, digits (0–9), hyphens (-), or dots (.)
  • Case: all lowercase; uppercase is never accepted

​
Allowed Characters

Character classAllowed
Lowercase letters a–zYes
Digits 0–9Yes
Hyphen -Yes
Dot .Yes
Uppercase letters A–ZNo
Underscore _No
SpacesNo
Any non-ASCII characterNo

​
Forbidden Patterns

Even if the character set is valid, the following patterns are rejected:
PatternExampleReason
Leading separator-my-tool, .my-toolMust start with a letter
Trailing separatormy-tool-, my-tool.Clean boundary
Consecutive hyphensmy--toolReserved for future scoping syntax
Consecutive dotsmy..toolAmbiguous hierarchy
Single charactera, xToo short to be meaningful

​
Reserved IDs

The following IDs (and IDs matching these prefixes) are permanently reserved and cannot be registered:
ReservedNotes
aipkg, aipkg-*, aipkg.*Registry-owned namespace
test, example, sampleCommonly used for demos; reserved to prevent pollution
api, admin, null, undefined, system, rootSystem words that conflict with registry routes or tooling
A push attempting to use a reserved ID receives 400 Bad Request with error code ID_RESERVED.

​
Publisher Scoping Conventions

AI•Pkg does not enforce namespacing at the syntax level — there is no @scope/name mechanism. Instead, publishers use two conventions:

​
Prefix convention

Use a consistent prefix separated by a hyphen: 
acme-git-helpers
acme-code-review
acme-typescript

​
Dot-group convention

Use dots to create an implicit hierarchy: 
acme.tools.git
acme.tools.typescript
acme.core
Both conventions are just that — conventions. The registry does not parse or enforce them. Enforcement happens through prefix reservations (see Prefix Reservations), which give verified publishers exclusive use of a prefix.

​
Display Names vs IDs

PropertyFieldNotes
Canonical identifieridImmutable; used in all API calls and URLs
Human-readable labeltitleOptional; shown in UI; no character restrictions except max 256 chars
If title is absent, the UI falls back to displaying id. Examples:
idtitle
git-helpers”Git Helper Skills”
acme.tools.git”Acme Git Toolkit”
filesystem-mcp”Filesystem MCP Server”

​
ID Immutability and Transfer

Once a package version is published:
  • The id cannot be changed — it is permanent for the life of the package
  • The id cannot be reused after a package is deleted — deleted IDs are tombstoned and permanently reserved
  • ID ownership can be transferred between registry accounts via a registry team support request

​
Tombstone Policy

When a package is deleted (not just unlisted), its ID is permanently reserved. A subsequent push with the same ID from any account receives 409 Conflict with error code ID_TOMBSTONED. This prevents dependency confusion attacks where a deleted package ID is re-registered with malicious content.

​
Validation Error Codes

The following error codes are returned by the registry and by AipkgValidator (see SDK Interface):
CodeCondition
ID_INVALID_PATTERNID does not match ^[a-z][a-z0-9\-\.]{0,127}$
ID_TOO_LONGID exceeds 128 characters
ID_RESERVEDID matches a system-reserved pattern
ID_FORBIDDEN_PATTERNID contains --, .., leading/trailing separator, or single character
ID_TOMBSTONEDID was previously registered and deleted
ID_PREFIX_CONFLICTID uses a reserved prefix owned by another publisher