Capability Standard (HXS-1)

HXS-1 is defined normatively by HeepX/standard — this page describes the subset the client's loader parses, not a competing definition.

A capability repository ships (among other required files — see standard/REPOSITORY_STRUCTURE.md):

| File | Required | Purpose | | ----------------- | -------- | -------------------------------------------------- | | CAPABILITY.yaml | yes | machine-readable descriptor (below) | | LICENSE | yes | the capability's own license | | spec/, eval/ | yes | the specification and the deterministic scorer |

CAPABILITY.yaml

A real example, from HeepX/warrant:

schema: heepx.capability/v1
id: warrant
version: 1.2.1
capability: >
  Deciding, per claim, whether to assert, cite, attribute, verify, or abstain —
  by naming the claim's warrant before emitting it.
improves:
  - hallucination rate on claims requiring unavailable evidence
does_not_improve:
  - factual accuracy of correctly-attributed recall
license: MIT
repository: https://github.com/HeepX/warrant
spec: EDP-1
model_agnostic: true
language_agnostic: true
deterministic_evaluation: true
requires_tools: false
composes_with:
  - any reasoning or planning scaffold
load_order:
  - path: spec/decision-procedure.md
    role: operational core
    cost: small
    sufficient_alone: true
evaluation:
  suite: eval/tasks.jsonl
  scorer: eval/score.py
  primary_metric: fabrication_rate
  guard_metric: over_hedge_rate
  run: python3 eval/score.py eval/tasks.jsonl submission.jsonl

Required keys: schema, id, version, capability, improves, does_not_improve, license. schema must be exactly heepx.capability/v1 — the only schema version the client currently understands. id must match the name the capability was requested under, or loading fails with InvalidCapabilityError.

model_agnostic, language_agnostic, deterministic_evaluation, requires_tools, and the evaluation block are optional but, when present, parsed into typed fields — evaluation.guard_metric exists specifically so a single metric can't be maximized by a policy that learned nothing.

Every path listed in load_order must exist in the archive, or loading fails the same way.

Loading one yourself

from pathlib import Path
from heepx.capability.loader import load_capability

capability = load_capability(Path("./warrant"), expected_name="warrant")
print(capability.metadata.capability)