.aispec file is a UTF-8 JSON document stored at the root of an .aipkg archive. It describes the package’s identity, metadata, capabilities, targeting, dependencies, and embedded assets. It corresponds to NuGet’s .nuspec but uses JSON instead of XML and contains AI•Pkg-specific fields.
File naming:
{id}.aispec — the filename must match the id field inside the manifest.JSON Schema
{
"$schema": "https://aipkg.org/schemas/aispec/1.0.0",
"type": "object",
"required": ["schema", "id", "version", "description", "authors", "capabilities"],
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"description": "Schema version URI. Must be 'https://aipkg.org/schemas/aispec/1.0.0'.",
"const": "https://aipkg.org/schemas/aispec/1.0.0"
},
"id": {
"type": "string",
"description": "Package identifier. Lowercase, alphanumeric, hyphens and dots only. Must match the filename ({id}.aispec).",
"pattern": "^[a-z][a-z0-9\\-\\.]{0,127}$",
"maxLength": 128
},
"version": {
"type": "string",
"description": "Semantic version string. SemVer 2.0.0 format. Pre-release and build metadata supported.",
"pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
},
"description": {
"type": "string",
"description": "Short description shown in search results. Plain text only. Max 500 characters.",
"minLength": 1,
"maxLength": 500
},
"authors": {
"type": "array",
"description": "One or more author names.",
"minItems": 1,
"maxItems": 10,
"items": { "type": "string", "minLength": 1, "maxLength": 200 }
},
"capabilities": {
"type": "array",
"description": "What this package provides. At least one required.",
"minItems": 1,
"items": {
"type": "string",
"enum": ["skill", "command", "agent", "prompt", "mcp-server", "lsp-server", "config", "hook", "theme"]
},
"uniqueItems": true
},
"targets": {
"type": "array",
"description": "APM monikers this package supports. Empty array or omitted means 'ai' (universal).",
"items": { "type": "string", "pattern": "^[a-z][a-z0-9\\-]{0,63}$" },
"uniqueItems": true,
"default": []
},
"title": {
"type": "string",
"description": "Human-readable display name. Falls back to id if omitted.",
"maxLength": 256
},
"summary": {
"type": "string",
"description": "One-line summary (shorter than description). Used in some UI contexts.",
"maxLength": 256
},
"releaseNotes": {
"type": "string",
"description": "What changed in this version. Markdown supported.",
"maxLength": 10000
},
"projectUrl": { "type": "string", "format": "uri" },
"repositoryUrl": { "type": "string", "format": "uri" },
"repositoryType": { "type": "string", "enum": ["git", "svn", "mercurial", "other"] },
"repositoryBranch": { "type": "string" },
"repositoryCommit": { "type": "string" },
"licenseExpression": { "type": "string" },
"licenseFile": { "type": "string" },
"iconFile": { "type": "string", "default": "icon.png" },
"readme": { "type": "string", "default": "README.md" },
"tags": {
"type": "array",
"description": "Search tags. Lowercase, alphanumeric and hyphens.",
"maxItems": 30,
"items": { "type": "string", "pattern": "^[a-z0-9\\-]{1,50}$" },
"uniqueItems": true
},
"copyright": { "type": "string", "maxLength": 500 },
"language": { "type": "string", "pattern": "^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{1,8})*$" },
"modelCompatibility": {
"type": "object",
"additionalProperties": false,
"properties": {
"minimumContextWindow": { "type": "integer", "minimum": 0 },
"requiresToolUse": { "type": "boolean" },
"requiresVision": { "type": "boolean" },
"notes": { "type": "string", "maxLength": 1000 }
}
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"filesystem:read", "filesystem:write",
"network:outbound", "network:inbound",
"process:exec",
"clipboard:read", "clipboard:write",
"env:read", "env:write",
"secrets:read"
]
},
"uniqueItems": true
},
"mcpServers": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "transport"],
"additionalProperties": false,
"properties": {
"name": { "type": "string", "pattern": "^[a-z][a-z0-9\\-]{0,63}$" },
"transport": { "type": "string", "enum": ["stdio", "sse", "http", "websocket"] },
"command": { "type": "string" },
"args": { "type": "array", "items": { "type": "string" } },
"url": { "type": "string", "format": "uri" },
"env": { "type": "object", "additionalProperties": { "type": "string" } },
"description": { "type": "string", "maxLength": 500 },
"targets": { "type": "array", "items": { "type": "string" } }
}
}
},
"lspServers": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "command"],
"additionalProperties": false,
"properties": {
"name": { "type": "string", "pattern": "^[a-z][a-z0-9\\-]{0,63}$" },
"command": { "type": "string", "description": "Executable to launch. May reference a file bundled in lsp/ using {install_path}." },
"args": { "type": "array", "items": { "type": "string" } },
"transport": { "type": "string", "enum": ["stdio"], "default": "stdio", "description": "LSP servers always use stdio per the LSP specification." },
"languages": {
"type": "array",
"description": "Language identifiers this server handles (e.g. 'python', 'typescript', 'rust'). At least one of languages or filetypes is recommended.",
"items": { "type": "string" }
},
"filetypes": {
"type": "array",
"description": "File extensions this server handles (e.g. '.py', '.ts'). Alternative to or combined with languages.",
"items": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" }
},
"env": { "type": "object", "additionalProperties": { "type": "string" } },
"initializationOptions": {
"type": "object",
"description": "Passed verbatim to the LSP initialize request as initializationOptions.",
"additionalProperties": true
},
"settings": {
"type": "object",
"description": "Workspace-level settings forwarded to the server via workspace/didChangeConfiguration.",
"additionalProperties": true
},
"description": { "type": "string", "maxLength": 500 },
"targets": { "type": "array", "items": { "type": "string" } }
}
}
},
"hooks": {
"type": "array",
"description": "Lifecycle hooks this package installs. Each entry declares an event, the path to its script or prompt file within the archive, and optional targeting.",
"items": {
"type": "object",
"required": ["event", "path"],
"additionalProperties": false,
"properties": {
"event": {
"type": "string",
"description": "The lifecycle event that triggers this hook.",
"enum": [
"PreToolUse",
"PostToolUse",
"Stop",
"SubagentStop",
"SessionStart",
"SessionEnd",
"UserPromptSubmit",
"PreCompact",
"Notification"
]
},
"matcher": {
"type": "string",
"description": "Glob pattern matched against the tool name. Only valid for PreToolUse and PostToolUse. Omit to match all tools."
},
"path": {
"type": "string",
"description": "Archive-relative path to the hook's script or prompt file (e.g. 'shared/hooks/pre-tool-use.md')."
},
"type": {
"type": "string",
"description": "Whether this hook runs as a prompt (sent to the model) or a script (executed as a subprocess).",
"enum": ["prompt", "script"],
"default": "prompt"
},
"description": { "type": "string", "maxLength": 500 },
"targets": { "type": "array", "items": { "type": "string" } }
}
}
},
"dependencies": {
"type": "array",
"items": {
"type": "object",
"required": ["id", "version"],
"additionalProperties": false,
"properties": {
"id": { "type": "string" },
"version": { "type": "string" },
"apms": { "type": "array", "items": { "type": "string" } },
"optional": { "type": "boolean", "default": false }
}
}
},
"listed": { "type": "boolean", "default": true },
"deprecated": {
"type": "object",
"additionalProperties": false,
"properties": {
"message": { "type": "string", "maxLength": 1000 },
"alternatePackageId": { "type": "string" },
"alternatePackageVersion": { "type": "string" }
}
}
}
}
Field Reference
Required Fields
| Field | Type | Notes |
|---|---|---|
schema | string | Must be "https://aipkg.org/schemas/aispec/1.0.0" |
id | string | Package ID. Must match filename. See Package Naming. |
version | string | SemVer 2.0.0. See Versioning. |
description | string | 1–500 chars |
authors | string[] | 1–10 authors |
capabilities | string[] | At least one capability |
Capability Values
| Value | Meaning |
|---|---|
skill | Provides one or more AI skills (.md skill files) |
command | Provides one or more slash commands |
agent | Provides one or more AI agent definitions |
prompt | Provides system prompts or prompt templates |
mcp-server | Bundles or configures an MCP server |
lsp-server | Bundles or configures a Language Server Protocol server |
config | Provides configuration files for a platform |
hook | Provides one or more lifecycle hooks (declared via hooks[]) |
theme | Provides UI theme or styling |
Permission Values
| Value | Meaning |
|---|---|
filesystem:read | Reads files from the local filesystem |
filesystem:write | Writes or modifies files |
network:outbound | Makes outbound network calls |
network:inbound | Listens for inbound connections |
process:exec | Executes subprocesses |
clipboard:read | Reads clipboard contents |
clipboard:write | Writes to clipboard |
env:read | Reads environment variables |
env:write | Modifies environment variables |
secrets:read | Reads secrets or credentials |
Platforms may enforce permissions at install or runtime. Installers must warn users when a package requests sensitive permissions (
process:exec, secrets:read, env:write).lspServers[] Fields
Each entry in lspServers configures one Language Server Protocol server the package installs.
| Field | Required | Type | Notes |
|---|---|---|---|
name | Yes | string | Unique identifier within the package. Lowercase alphanumeric and hyphens. |
command | Yes | string | Executable to launch. Use {install_path} to reference bundled files in lsp/. |
args | No | string[] | Command-line arguments passed to the executable. |
transport | No | string | Always "stdio" (LSP specification). Default: "stdio". |
languages | No | string[] | Language identifiers this server handles (e.g. "python", "typescript"). |
filetypes | No | string[] | File extensions this server handles (e.g. ".py", ".ts"). |
env | No | object | Environment variables set before launching the server. |
initializationOptions | No | object | Passed verbatim to the LSP initialize request. |
settings | No | object | Workspace settings forwarded via workspace/didChangeConfiguration. |
description | No | string | Human-readable description. Max 500 chars. |
targets | No | string[] | APM monikers this server applies to. Empty means all platforms. |
hooks[] Fields
Each entry in hooks declares one lifecycle hook the package installs. Requires the hook capability.
| Field | Required | Type | Notes |
|---|---|---|---|
event | Yes | string | Lifecycle event that triggers this hook. See event table below. |
path | Yes | string | Archive-relative path to the hook file (e.g. "shared/hooks/pre-tool-use.md"). |
type | No | string | "prompt" (sent to model) or "script" (executed as subprocess). Default: "prompt". |
matcher | No | string | Glob pattern matched against the tool name. Only valid for PreToolUse and PostToolUse. |
description | No | string | Human-readable description. Max 500 chars. |
targets | No | string[] | APM monikers this hook applies to. Empty means all platforms. |
| Event | Trigger |
|---|---|
PreToolUse | Before any tool call. Use matcher to filter by tool name. |
PostToolUse | After any tool call completes. Use matcher to filter by tool name. |
Stop | When the agent reaches a stopping point and returns control to the user. |
SubagentStop | When a subagent finishes and returns to its parent. |
SessionStart | At the beginning of a new conversation session. |
SessionEnd | At the end of a conversation session. |
UserPromptSubmit | After the user submits a prompt, before the model responds. |
PreCompact | Before the context window is compacted. |
Notification | When the platform surfaces a system notification. |
Examples
- Simple Skill Package
- MCP Server Package
- Multi-Capability with Dependencies
- LSP Server Package
- Hooks Package
{
"schema": "https://aipkg.org/schemas/aispec/1.0.0",
"id": "git-helpers",
"version": "1.0.0",
"title": "Git Helper Skills",
"description": "A collection of Git workflow skills for AI coding assistants.",
"authors": ["Jane Developer"],
"capabilities": ["skill"],
"targets": ["claude-code", "copilot-vscode", "cursor"],
"licenseExpression": "MIT",
"projectUrl": "https://github.com/jane/git-helpers",
"repositoryUrl": "https://github.com/jane/git-helpers",
"repositoryType": "git",
"tags": ["git", "workflow", "version-control"],
"iconFile": "icon.png",
"readme": "README.md"
}
{
"schema": "https://aipkg.org/schemas/aispec/1.0.0",
"id": "filesystem-mcp",
"version": "2.1.0",
"title": "Filesystem MCP Server",
"description": "MCP server providing secure filesystem access tools to AI platforms.",
"authors": ["MCP Foundation"],
"capabilities": ["mcp-server"],
"targets": ["claude-code", "cursor", "opencode"],
"licenseExpression": "Apache-2.0",
"permissions": ["filesystem:read", "filesystem:write"],
"modelCompatibility": { "requiresToolUse": true },
"mcpServers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "{install_path}"],
"description": "Provides read/write access to the filesystem.",
"targets": []
}
],
"tags": ["mcp", "filesystem", "tools"],
"projectUrl": "https://github.com/mcp/filesystem-server"
}
{
"schema": "https://aipkg.org/schemas/aispec/1.0.0",
"id": "full-stack-dev",
"version": "3.0.0-beta.1",
"title": "Full Stack Development Suite",
"description": "Complete set of skills, commands, and prompts for full-stack web development.",
"authors": ["Dev Tools Co.", "Jane Developer"],
"capabilities": ["skill", "command", "prompt"],
"targets": ["claude-code"],
"licenseExpression": "MIT",
"tags": ["fullstack", "web", "typescript", "react"],
"releaseNotes": "## 3.0.0-beta.1\n- Added React skill\n- Improved TypeScript commands",
"modelCompatibility": {
"minimumContextWindow": 100000,
"requiresToolUse": true
},
"dependencies": [
{ "id": "git-helpers", "version": "[1.0.0,2.0.0)", "apms": ["claude-code"] },
{ "id": "filesystem-mcp", "version": "2.0.0", "apms": [], "optional": true }
]
}
{
"schema": "https://aipkg.org/schemas/aispec/1.0.0",
"id": "python-language-server",
"version": "1.4.0",
"title": "Python Language Server",
"description": "Bundles and configures Pyright for AI coding assistants that support LSP.",
"authors": ["AI•Pkg Contributors"],
"capabilities": ["lsp-server"],
"targets": ["claude-code", "cursor", "opencode"],
"licenseExpression": "MIT",
"permissions": ["process:exec", "filesystem:read"],
"lspServers": [
{
"name": "pyright",
"command": "pyright-langserver",
"args": ["--stdio"],
"transport": "stdio",
"languages": ["python"],
"filetypes": [".py", ".pyi"],
"initializationOptions": {
"pythonVersion": "3.11"
},
"settings": {
"python": {
"analysis": {
"typeCheckingMode": "basic"
}
}
},
"description": "Pyright static type checker and language server for Python."
}
],
"tags": ["python", "lsp", "type-checking", "pyright"]
}
{
"schema": "https://aipkg.org/schemas/aispec/1.0.0",
"id": "safety-hooks",
"version": "1.0.0",
"title": "Safety Guardrail Hooks",
"description": "Lifecycle hooks that prompt the model to review dangerous operations before and after execution.",
"authors": ["Safety Team"],
"capabilities": ["hook"],
"targets": ["claude-code"],
"licenseExpression": "Apache-2.0",
"hooks": [
{
"event": "PreToolUse",
"matcher": "Bash",
"path": "shared/hooks/pre-bash-review.md",
"type": "prompt",
"description": "Asks the model to review shell commands for destructive patterns before execution."
},
{
"event": "PreToolUse",
"matcher": "Edit",
"path": "shared/hooks/pre-edit-review.md",
"type": "prompt",
"description": "Asks the model to verify file edits are consistent with stated intent."
},
{
"event": "PostToolUse",
"matcher": "Bash",
"path": "shared/hooks/post-bash-log.md",
"type": "prompt",
"description": "Logs executed shell commands for audit purposes."
},
{
"event": "SessionStart",
"path": "shared/hooks/session-start.md",
"type": "prompt",
"description": "Reminds the model of safety guidelines at the start of each session."
}
],
"tags": ["safety", "hooks", "guardrails", "audit"]
}
Validation Rules
Beyond JSON Schema conformance, the registry enforces these additional rules:ID and version rules
ID and version rules
- ID uniqueness: The combination of
id+versionmust be unique on the registry. - ID immutability: Once published, a version’s
idcannot change. - Version uniqueness: Once a version is published, it cannot be republished (even after deletion).
- Filename match: The
.aispecfilename must match theidfield exactly.
Asset rules
Asset rules
- Icon format:
iconFilemust reference a valid square PNG (validated server-side). - MCP server names: All
mcpServers[].namevalues within a single package must be unique. - LSP server names: All
lspServers[].namevalues within a single package must be unique. - Hook matcher scope:
hooks[].matcheris only permitted wheneventisPreToolUseorPostToolUse. Setting it on any other event is a validation error. - Hook capability: Packages that declare entries in
hooks[]must include"hook"incapabilities. - LSP capability: Packages that declare entries in
lspServers[]must include"lsp-server"incapabilities.
Dependency rules
Dependency rules
- Dependency cycles: Circular dependencies are rejected at push time (server resolves the full graph).
License recommendation
License recommendation
- License: At least one of
licenseExpressionorlicenseFileis strongly recommended. A warning (not error) is emitted if both are absent.
Relationship to .nuspec
.nuspec Field | .aispec Equivalent | Notes |
|---|---|---|
<id> | id | Same |
<version> | version | Same format (SemVer) |
<authors> | authors[] | Array instead of comma-delimited string |
<description> | description | Same |
<packageType> | capabilities[] | Array of typed values instead of single type |
<dependencies targetFramework> | dependencies[].apms[] | APMs instead of TFMs |
<requireLicenseAcceptance> | (dropped) | Not supported |
<developmentDependency> | (dropped) | Not supported |
<semVerLevel> | (dropped) | Always SemVer 2.0.0 |
| (no equivalent) | capabilities[] | New |
| (no equivalent) | targets[] | New |
| (no equivalent) | permissions[] | New |
| (no equivalent) | mcpServers[] | New |
| (no equivalent) | lspServers[] | New |
| (no equivalent) | hooks[] | New |
| (no equivalent) | modelCompatibility | New |