AI Catalog

A .NET and Python toolkit for working with AI Catalog documents (application/ai-catalog+json). Parse, validate, serialize, explore, and install AI artifacts from catalog registries.

What is AI Catalog?

AI Catalog is an open specification for describing collections of AI artifacts — agent cards, MCP server cards, skills, and other machine-readable resources. It provides a standardized format for discovery, trust, and installation of AI components.

Key concepts:

  • Catalog — A JSON document listing AI artifacts with metadata
  • Entry — A single artifact with identifier, media type, URL or embedded data, and optional trust manifest
  • Conformance Levels — Minimal (Level 1), Discoverable (Level 2), Trusted (Level 3)

Packages

Package Language Install
SpecWorks.AiCatalog .NET 8/10 dotnet add package SpecWorks.AiCatalog
SpecWorks.AiCatalog.Cli .NET 9 CLI dotnet tool install --global SpecWorks.AiCatalog.Cli
specworks-aicatalog Python pip install specworks-aicatalog

Quick Start — Library (.NET)

using SpecWorks.AiCatalog.Parsing;
using SpecWorks.AiCatalog.Validation;
using SpecWorks.AiCatalog.Serialization;

// Parse a catalog document
var json = File.ReadAllText("ai-catalog.json");
var catalog = AiCatalogParser.Parse(json);

// Validate conformance level
var result = AiCatalogValidator.Validate(catalog);
Console.WriteLine($"Conformance: {result.ConformanceLevel}"); // Minimal, Discoverable, or Trusted

// Iterate entries
foreach (var entry in catalog.Entries)
{
    Console.WriteLine($"{entry.DisplayName} ({entry.MediaType})");
}

// Serialize back to JSON
var output = AiCatalogSerializer.Serialize(catalog);

Quick Start — Library (Python)

from aicatalog import parse, serialize, validate

catalog = parse('{"specVersion": "1.0", "entries": []}')
result = validate(catalog)
print(result.conformance_level)  # ConformanceLevel.MINIMAL
json_str = serialize(catalog)

Quick Start — CLI

# Install the CLI tool
dotnet tool install --global SpecWorks.AiCatalog.Cli

# Explore a remote catalog
ai-catalog explore https://spec-works.github.io/.well-known/ai-catalog.json

# Show details for a specific entry
ai-catalog explore https://spec-works.github.io/.well-known/ai-catalog.json --show "urn:specworks:a2a-ask"

# Filter by tag
ai-catalog explore https://spec-works.github.io/.well-known/ai-catalog.json --filter-tag agent

# Migrate a marketplace.json to ai-catalog format
ai-catalog migrate marketplace.json -o ai-catalog.json

# Export an AI Catalog to platform-specific outputs
ai-catalog export ai-catalog.json -o out

# Publish a catalog package (stub)
ai-catalog publish ai-catalog.json -o dist

# Install an artifact from a catalog
ai-catalog install https://spec-works.github.io/.well-known/ai-catalog.json "urn:specworks:a2a-ask"

CLI Commands

Command Description
ai-catalog migrate <file> Migrate a marketplace.json to AI Catalog format
ai-catalog export <file> -o <dir> Export an AI Catalog to platform-specific plugin formats
ai-catalog publish <file> -o <dir> Package a catalog for remote distribution (currently a stub)
ai-catalog explore <url> Fetch and browse an AI Catalog from a URL
ai-catalog install <catalog-url> <entry-id> Install an artifact (skill or MCP server) from a catalog

migrate

Migrates a Claude-format marketplace.json into a standard ai-catalog.json document.

Option Description
-o, --output <file> Output file path (defaults to stdout)

export

Exports an ai-catalog.json file into platform-specific plugin marketplace formats.

Option Description
-o, --output <dir> Output directory for generated plugin marketplace files
--source-dir <dir> Base directory for resolving relative plugin source paths
--github Generate GitHub Copilot CLI marketplace output
--codex Generate OpenAI Codex CLI marketplace output
--claude Generate Claude Code plugin marketplace output

publish

Packages a catalog for remote distribution (zip, signing, hosting). This command currently prints Not yet implemented.

install

Downloads and installs an artifact from a catalog. Auto-detects MCP server cards vs skills.

Option Description
--type <mcp\|skill> Override auto-detection
--output-dir <dir> Base directory for installation (default: .)

.NET Library API

Parsing

// From string
var catalog = AiCatalogParser.Parse(jsonString);

// From stream
using var stream = File.OpenRead("catalog.json");
var catalog = AiCatalogParser.Parse(stream);

Validation

var result = AiCatalogValidator.Validate(catalog);
// result.ConformanceLevel: Minimal (1), Discoverable (2), or Trusted (3)
// result.Errors: list of validation issues
// result.IsValid: true if no errors

Serialization

// To string
var json = AiCatalogSerializer.Serialize(catalog);

// To stream
AiCatalogSerializer.Serialize(catalog, outputStream);

Models

  • AiCatalog — Top-level document with SpecVersion, Entries, optional Host and Metadata
  • CatalogEntry — An artifact entry with Identifier, DisplayName, MediaType, Url/Data, Publisher, TrustManifest, Tags
  • HostInfo — Catalog operator info
  • Publisher — Entry publisher info
  • TrustManifest — Trust and attestation data

A2A Discovery Helpers

Use the helper surface in SpecWorks.AiCatalog when you need to identify A2A agent cards inside a catalog.

  • KnownMediaTypes.AiCatalog — application/ai-catalog+json
  • KnownMediaTypes.A2AAgentCard — application/a2a-agent-card+json
  • KnownMediaTypes.A2AAgentCardVendor — application/vnd.a2a.agent-card+json
  • CatalogEntryExtensions.IsA2AAgentCard() — returns true when a CatalogEntry media type matches either A2A agent card media type, using case-insensitive comparison.
using SpecWorks.AiCatalog;
using SpecWorks.AiCatalog.Models;

CatalogEntry entry = GetEntry();

if (entry.IsA2AAgentCard())
{
    Console.WriteLine($"Resolved A2A entry: {entry.Identifier}");
}

Specification

This library implements the AI Card specification (application/ai-catalog+json), including:

  • VH-1: specVersion validation (Major.Minor format)
  • VH-2: Unknown properties preserved via [JsonExtensionData]
  • VH-4/5/6: Major version compatibility checking
  • Conformance levels: Minimal → Discoverable → Trusted

Contributing

See the SpecWorks Factory for contributing guidelines.

License

MIT

Additional Resources

Edit this page