artifact-api-contract.md

Static Artifact API Contract

Contract version: static-artifact-api-v1

This document defines the public JSON artifact surface for registry consumers. The artifacts are generated by claude-skill-registry-core; generated files in the merged claude-skill-registry repository are publish outputs, not source files to patch by hand.

Locations

• Core Pages base URL: https://majiayu000.github.io/claude-skill-registry-core/
• Merged artifact raw base URL: https://raw.githubusercontent.com/majiayu000/claude-skill-registry/main/

Core Pages is optimized for the web app and public read APIs. The merged artifact is optimized for bulk registry compatibility and raw archive browsing.

Public Entry Points

Path	Location	Contract
search-index-lite.json	Core Pages	Startup catalog index with deduped summaries and quality/security signals.
search-index.json	Core Pages	Compatibility pointer for the full search payload.
search-index-manifest.json	Core Pages	Full search shard manifest.
search-shards/part-000.json	Core Pages	Full search shard part pattern.
featured.json	Core Pages	Featured skills for the web app.
plugins.json	Core Pages	Plugin catalog.
stats.json	Core Pages	Generated counts, shard sizes, and summary statistics.
quality-index.json	Core Pages	Compatibility pointer for quality records.
quality-index-manifest.json	Core Pages	Quality shard manifest.
quality-shards/part-000.json	Core Pages	Quality shard part pattern.
security-index.json	Core Pages	Compatibility pointer for security records.
security-index-manifest.json	Core Pages	Security shard manifest.
security-shards/part-000.json	Core Pages	Security shard part pattern.
ranking-index.json	Core Pages	Compatibility pointer for ranking records.
ranking-index-manifest.json	Core Pages	Ranking shard manifest.
ranking-shards/part-000.json	Core Pages	Ranking shard part pattern.
categories/index.json	Core Pages	Category manifest index.
categories/<category>.json	Core Pages	Legacy category compatibility pointer.
categories/<category>/manifest.json	Core Pages	Category part manifest.
categories/<category>/part-000.json	Core Pages	Category part pattern.
registry_summary.json	Core raw	Lightweight source summary and counts.
registry.json	Merged raw	Compatibility pointer for the full registry payload.
registry-manifest.json	Merged raw	Registry shard manifest.
registry-shards/00.json	Merged raw	Registry shard pattern, keyed by two-character shard id.
provenance/merge-source.json	Merged raw	Source refs used for the merged publish artifact.

Any new public JSON artifact must be added to this table in the same PR that adds or changes the generated artifact.

Compatibility Pointers

Large historical full-payload files are now small pointer files. A pointer object must include:

• deprecated_full_payload: true
• message
• manifest when the replacement manifest is published next to the pointer
• compat_since
• replacement

Pointer files must not contain a full skills or records payload. Consumers must follow manifest or replacement instead of assuming the compatibility file contains all records.

Current pointer entry points:

• search-index.json
• quality-index.json
• security-index.json
• ranking-index.json
• categories/<category>.json
• registry.json

Manifests

Manifest objects must include a schema_version, an updated_at or generated_at timestamp, a record count, and shard or part references.

Search, quality, security, and ranking manifests use shard entries with:

• path
• gzip_path when a gzip artifact is written
• count
• bytes
• gzip_bytes when a gzip artifact is written
• sha256

Category manifests use part entries with:

• path
• gzip_path
• count
• bytes
• gzip_bytes
• sha256

Registry manifests use shard entries with:

• id
• path
• gzip_path
• count
• bytes
• gzip_bytes
• sha256

Consumers should validate sha256 when they need reproducible syncs. Consumers should prefer gzip_path when bandwidth matters and plain path when a simpler client is more important.

Shard Payloads

Shard payloads must include:

• schema_version
• an identity field for the shard or part
• count
• a bounded payload array

Search shard payload arrays are skills. Signal shard payload arrays are records. Category part payload arrays are skills. Registry shard payload arrays are skills.

Security signal records expose security_status plus security_decision when scanner evidence was available. The decision object contains the scanner name, scanner version, ruleset hash, source content hash, scan timestamp, and a deterministic decision id. Missing security decisions must be treated as unknown evidence, not clean evidence.

Shard ordering is deterministic for a given generator version, but consumers must not treat ordering as a stable API unless the manifest explicitly documents the ordering strategy.

Deprecation Rules

Removing or changing a public entry point is a breaking change. A breaking change must either:

• add a new path and leave the old path as a compatibility pointer, or
• update this contract with a migration note and a compatibility window.

Compatibility pointer fields:

• compat_since: first date or version when the pointer behavior was present
• compat_until: optional planned end of compatibility
• replacement: path or path pattern consumers should use

If compat_until is absent, consumers may assume no removal date has been announced yet.

Consumer Guidance

For startup search, use search-index-lite.json first. For exhaustive search, follow search-index.json to search-index-manifest.json, then load the listed search shards.

For category browsing, load categories/index.json, then follow the selected category manifest and parts. Do not fetch every category part on startup.

For trust and ranking overlays, load the pointer, then the corresponding manifest and shards. Treat missing signal records as unknown, not clean.

For full registry sync, use the merged artifact registry-manifest.json and registry-shards/*.json. Use registry.json only as a compatibility pointer.