Runtime Integration Contract

Responsibility Boundary

SkillHub and Agent Runtime own different facts:

System	Source of truth
SkillHub	Skill packages, versions, metadata, compliance declaration snapshots, downloads, and review records
Agent Runtime	Actual skill execution, inputs and outputs, model calls, tool calls, and execution traces

SkillHub does not execute skills, so it does not record Runtime traces and does not decide whether a real execution was compliant. SkillHub provides version-level facts: what compliance declarations were included in an immutable skill version at publish time, and the stable digest of that normalized snapshot.

What Runtime Should Record

When Runtime needs to connect an execution trace with SkillHub compliance declarations, record these fields:

Field	Source	Description
registryUrl	Runtime configuration	SkillHub registry URL
namespace	SkillHub coordinate	Skill namespace, such as global or a team slug
skillSlug	SkillHub coordinate	Skill slug
requestedVersion	Runtime request	User-requested version, tag, or range
resolvedVersion	SkillHub response	Exact resolved version
skillVersionId	Version id from SkillHub response	Immutable version ID and the primary audit join key
complianceSnapshotDigest	complianceSnapshot.digest	Stable digest of the version-level compliance declaration snapshot
packageDigest	Download or install flow	Skill package content digest, useful for confirming executed content
runtimeTraceId	Runtime	Execution trace ID generated by Runtime

If Runtime uses an Astron-specific trace schema, it may map these fields into x-astron-* keys. That is a Runtime-owned trace convention; SkillHub server does not need to write or parse those trace fields.

Reading Version-Level Compliance Snapshots

The first phase does not expose a standalone compliance API. Runtime can read the version ID and snapshot from the existing version detail endpoint:

GET /api/v1/skills/{namespace}/{slug}/versions/{version}

Key response fields:

{
  "id": 123,
  "version": "1.2.0",
  "complianceSnapshot": {
    "schemaVersion": "1.0",
    "digest": "sha256:8d8c...",
    "items": [
      {
        "standard": "mitre-attack",
        "version": "v19.1",
        "controlId": "T1059",
        "title": "Command and Scripting Interpreter",
        "evidence": [
          {
            "type": "packaged-file",
            "path": "references/mitre-t1059.md",
            "sha256": "sha256:..."
          }
        ]
      }
    ]
  }
}

Runtime should write both id and complianceSnapshot.digest to the execution trace. Recording only the digest is not enough, because the version ID is needed to locate the full snapshot across registries or future migrations.

Recommended Execution Flow

1. Runtime resolves the requested skill coordinate and version.
2. Runtime reads exact version details from SkillHub.
3. Runtime downloads and verifies the skill package.
4. Runtime executes the skill.
5. Runtime records these facts in its own trace:
   • SkillHub registry;
   • skill coordinate;
   • exact version;
   • skillVersionId;
   • complianceSnapshotDigest;
   • Runtime-owned execution evidence.

An audit system can then start from the Runtime trace, locate the exact execution, and query SkillHub for the compliance declaration snapshot that existed when that version was published.

Anti-Patterns

• Do not copy the raw x-astron-compliance declaration into a trace and let Runtime mutate it.
• Do not record only the skill slug without the version ID; the slug identifies the skill container, not an immutable version.
• Do not treat SkillHub compliance declarations as third-party certification.
• Do not require SkillHub to record model inputs and outputs; that belongs to the Runtime audit boundary.

Possible Future API

If a clear consumer appears, such as Runtime needing only the compliance snapshot without full skill details, SkillHub can add an immutable version-level endpoint:

GET /api/skill-versions/{skillVersionId}/compliance

For now, reuse the version detail response to avoid designing multiple APIs before the caller contract is stable.