Skip to content

artifact-api-contract.md

Latest commit

 

History

History
267 lines (207 loc) · 10.7 KB

artifact-api-contract.md

File metadata and controls

267 lines (207 loc) · 10.7 KB
Raw

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:

  • schema_version: 1
  • total_count as the canonical non-negative record count
  • deprecated_full_payload: true
  • message
  • manifest
  • compat_since
  • compat_until
  • replacement

Pointer files must not contain a full skills, records, or s 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

Compatibility count aliases are limited to the following V1 window. Every alias must equal total_count; unlisted aliases are invalid.

Pointer Canonical count Allowed alias Window
search-index.json total_count t static-artifact-api-v1 through static-artifact-api-v2
quality/security/ranking pointers total_count count static-artifact-api-v1 through static-artifact-api-v2
categories/<category>.json total_count count static-artifact-api-v1 through static-artifact-api-v2
registry.json total_count registry_skill_count_dedup static-artifact-api-v1 through static-artifact-api-v2

Manifests

Manifest objects must include schema_version: 1, an updated_at or generated_at timestamp, canonical total_count, an exact shard/part count, and shard or part references. Entry counts must sum to total_count.

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

Category manifests also publish part_strategy: bounded-sequential-stars-desc. Parts are ordered by stars descending, then name and install path, so consumers may fetch only the first part for a bounded top-skills leaderboard. Consumers must fail closed if this strategy or the first-part identity/count metadata is absent or invalid.

Registry manifests use shard entries with:

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

The registry manifest contains exactly the canonical 256 lowercase hexadecimal ids 00 through ff, once each. An id maps only to registry-shards/<id>.json and registry-shards/<id>.json.gz; the payload shard must equal that id. Every registry skill belongs to the first two hexadecimal characters of sha256("<skill-install-key>|<branch>"), where the install key is repo/path, then repo, then local/path, then local/category/name; an absent or empty branch is main.

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 s. Lite search document payload arrays are skills. Signal shard payload arrays are records. Category part payload arrays are skills. Registry shard payload arrays are skills.

Each shard/part count must equal its payload array length and manifest entry count. Manifest entry bytes, gzip_bytes, and sha256 describe the referenced plain/gzip files exactly; gzip JSON must be structurally identical to plain JSON.

Same-set Count Groups

Counts are compared only inside explicitly identical sets:

  • Registry dedup set: registry.json, registry-manifest.json, registry_summary.json, and stats.json.registry_skill_count_dedup.
  • Search/category scan set: search pointer/manifest, category index/manifests, and stats.json.indexed_skill_count_scan_shape.
  • Stable-id dedup set: lite search, quality/security/ranking pointers/manifests, and stats.json.lite_index_count.

Featured subsets, plugin counts, and raw archive counts are not compared to these groups.

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: planned end of this V1 compatibility window
  • replacement: path or path pattern consumers should use

compat_until is required for every V1 compatibility pointer. Consumers must treat a pointer without it as invalid rather than guessing an unannounced removal date.

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.

Asset facets are optional. Registry and lite/full search records use asset_state and asset_liveness; compact search records use a and l. Missing fields mean no validated asset evidence and must remain blank rather than being presented as a failed or verified bundle. Ranking records expose the non-negative asset_ranking_penalty; verified-live evidence has zero penalty.

For full registry sync, consumers should prefer manifests and bounded shards to giant single-payload JSON files. Load the merged artifact registry-manifest.json and every shard it lists; registry.json is compatibility-only. Missing manifests or shards, invalid JSON, and malformed payload shapes are errors and must not be silently ignored.

Minimal standard-library Python example:

import json
from urllib.parse import urljoin
from urllib.request import urlopen

manifest_url = (
    "https://raw.githubusercontent.com/majiayu000/"
    "claude-skill-registry/main/registry-manifest.json"
)


def load_json(url):
    with urlopen(url) as response:
        return json.load(response)


manifest = load_json(manifest_url)
if not isinstance(manifest, dict):
    raise ValueError("registry manifest must be a JSON object")
shards = manifest.get("shards")
if not isinstance(shards, list) or not shards:
    raise ValueError("registry manifest must contain a non-empty 'shards' list")

skills = []
for shard in shards:
    if not isinstance(shard, dict):
        raise ValueError("registry shard entries must be JSON objects")
    path = shard.get("path")
    if not isinstance(path, str) or not path:
        raise ValueError("registry shard entries must contain a non-empty 'path'")
    shard_url = urljoin(manifest_url, path)
    payload = load_json(shard_url)
    if not isinstance(payload, dict) or not isinstance(payload.get("skills"), list):
        raise ValueError(f"{shard_url} must contain a 'skills' list")
    skills.extend(payload["skills"])

print(f"loaded {len(skills)} skills")

The example intentionally lets HTTP and JSON decoding errors propagate so a partial registry sync cannot look successful.