Skill Contract Schema

1.Abstract#

This specification defines the Skill Contract Schema, a typed, declarative format for describing the inputs, outputs, evidence, side effects, risk class, and required approvals of an AI skill. A conforming Skill Contract is a YAML or JSON document that validates against the normative JSON Schema in Section 8 and provides every field marked REQUIRED in Section 7. The Skill Contract is the unit of artifact that makes an AI skill reviewable, testable, governable, and auditable.

2.Problem statement#

2.1The problem#

AI skills are routinely shipped without a typed contract. The system that invokes the skill knows it returns “a response”; the team that operates it knows it “does the right thing most of the time”; the reviewer asked to approve it knows it “is being used in production.” No party holds a precise statement of what the skill takes, what it returns, what it touches on the way through, or what evidence it leaves behind.

The cost of this opacity compounds. A skill without a contract cannot be validated against a schema, so its callers must guess. It cannot be evaluated against a reference suite, so its quality cannot be measured. It cannot be reviewed by a governance body, so it ships under unstated assumptions. It cannot be audited by a regulator, because the artifact a regulator would inspect does not exist. When the skill behaves unexpectedly — or when an incident requires reconstruction — there is no document that says what it was supposed to do.

The Skill Contract Schema treats this opacity as the primary defect to repair. It defines a small, dense, machine-checkable format whose presence is the precondition for every downstream discipline: typed validation, evaluation, governance review, evidence capture, and post-incident reconstruction. A skill without a conforming contract is, for the purposes of this specification and the disciplines that build on it, undefined.

2.2What this spec solves#

This specification defines a single artifact — the Skill Contract — in a single format that is both human-authorable and machine-verifiable. A conforming contract makes a skill’s boundary, behavior, side effects, sensitivity classification, and accountable owner explicit. The contract is the foundation on which validation tooling, eval suites, governance approvals, and audit evidence are built.

2.3What this spec does NOT solve#

The following are explicitly out of scope for this specification:

• Implementation of the skill itself. The contract describes behavior; it does not prescribe how the behavior is produced, which model is invoked, or which framework hosts it.
• Runtime enforcement. How a runtime intercepts invocations, validates inputs against the contract, captures evidence, or rejects unauthorized callers is the concern of the runtime, not this spec.
• Evaluation methodology. The contract may reference an eval suite and declare a required pass rate, but the methodology by which evals are authored, executed, and scored is governed by the Maturity Gate Model (IM-05).
• Approval workflow tooling. The contract names required approvals; how those approvals are routed, collected, and recorded is the concern of the surrounding governance system.

3.Conformance language#

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document carry the specific normative meanings defined below. Where these words appear in lowercase, they carry their ordinary English meaning and impose no normative requirement.

4.Definitions#

The following terms are used throughout this specification with the precise meanings defined here. Where a term is used in this specification, it carries this meaning unless explicitly noted otherwise.

5.Core concepts#

5.1Skill#

A skill is a discrete, named unit of AI behavior governed by a contract. Skills are identified by a stable skill.id and versioned independently of the systems that invoke them. A skill MUST have exactly one contract at any given version; a skill MAY exist at multiple versions simultaneously, each with its own contract.

5.2Contract#

A contract is the declarative description of a skill’s behavior. It is authored alongside the skill and travels with it. A contract MUST NOT contain implementation. A skill without a conforming contract is, for the purposes of this specification, undefined.

5.3Invocation#

An invocation is a single execution of the skill, governed by the contract that was current at the moment of execution. Every invocation MUST be bound to a single contract version and MUST produce evidence in the form prescribed by that contract.

5.4Evidence#

Evidence is the artifact produced or referenced by a skill that allows an invocation to be reconstructed and audited later. Evidence is the substrate of the Evidence-by-Design Framework (IM-03). Without evidence, an invocation cannot be reconstructed, and therefore cannot be governed.

5.5Relationship between concepts#

The four concepts compose. A skill exposes a contract. The contract bounds every invocation of the skill. Each invocation produces evidence. The evidence is what a reviewer, auditor, or incident responder inspects when the skill’s behavior must be explained. Each concept stands or falls with the one before it. A missing contract leaves an invocation ungoverned. Missing evidence leaves an invocation unauditable.

6.The Skill Contract format#

A conforming Skill Contract MUST be a YAML or JSON document with the structure defined below. The example illustrates a complete, valid contract for a regulated lending skill; all required sections are present.

The canonical surface form for human authoring is YAML. JSON is acceptable for machine emission. Both forms MUST validate against the normative schema in Section 8.

Example 1 — Complete Skill Contract (YAML)

# innorve-skill-contract v0.1
schema: innorve.skill-contract.v0.1
skill:
  id: bank.lending.heloc-eligibility-check
  name: HELOC Eligibility Check
  version: 1.2.0
  owner: lending-engineering@example-bank.test
  description: |
    Given an applicant's profile, returns whether they meet baseline
    eligibility for a Home Equity Line of Credit. Does not approve,
    decline, or commit to a rate.

caller:
  type: human                  # one of: human, agent, system
  authentication: required
  authorized_roles: [loan-officer, lending-app-frontend]

inputs:
  - name: applicant_profile
    type: object
    schema_ref: schemas/applicant_profile.v3.json
    required: true
    sensitivity: pii
  - name: requested_amount
    type: number
    unit: USD
    required: true
    min: 1000
    max: 5000000

outputs:
  - name: eligibility
    type: enum
    values: [eligible, eligible_with_conditions, not_eligible, indeterminate]
    required: true
  - name: conditions
    type: array
    items: string
    required: false
  - name: confidence
    type: number
    min: 0.0
    max: 1.0
    required: true

evidence:
  required:
    - source_documents         # which policy documents were referenced
    - rule_evaluation_trace    # which rules fired in what order
    - confidence_breakdown     # the inputs into the confidence score
  format: innorve.evidence.v0.1
  retention_days: 2555         # 7 years

side_effects:
  external_calls:
    - service: credit-bureau-api
      data_sent: [tokenized_ssn, requested_amount]
      idempotent: true
  writes:
    - audit_log
  does_not:
    - approve_loan
    - send_customer_communication
    - access_other_accounts

risk_class: high               # one of: low, medium, high, critical
required_approvals:
  - reviewer: model-risk-management
    when: deployment_to_production
  - reviewer: chief-compliance-officer
    when: risk_class_change_proposed

evals:
  reference: evals/heloc-eligibility-check.v1.evals.yaml
  required_pass_rate: 0.95
  regression_tests: 12

deprecation:
  status: active               # one of: incubating, validated, certified, deprecated
  sunset_date: null

7.Field definitions#

The following table enumerates the top-level and nested fields defined by this specification. Fields not listed here are not part of the v0.1 schema; conforming tools SHOULD preserve unknown fields without interpreting them.

8.JSON Schema (normative)#

The JSON Schema below is normative. A document that fails JSON Schema validation against this schema MUST NOT be considered a conforming Skill Contract.

The canonical version is published at the $id URL below and SHOULD be fetched programmatically by tooling. Implementations MAY embed a copy of the schema for offline validation, provided the embedded copy matches the canonical version exactly.

Schema — innorve.skill-contract.v0.1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://innorve.academy/spec/skill-contract/v0.1.json",
  "title": "Innorve Skill Contract Schema",
  "type": "object",
  "required": [
    "schema",
    "skill",
    "caller",
    "inputs",
    "outputs",
    "evidence",
    "side_effects",
    "risk_class",
    "deprecation"
  ],
  "properties": {
    "schema": {
      "type": "string",
      "const": "innorve.skill-contract.v0.1"
    },
    "skill": {
      "type": "object",
      "required": ["id", "name", "version", "owner", "description"],
      "properties": {
        "id":          { "type": "string", "pattern": "^[a-z0-9.-]+$" },
        "name":        { "type": "string" },
        "version":     { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
        "owner":       { "type": "string", "format": "email" },
        "description": { "type": "string" }
      }
    },
    "caller": {
      "type": "object",
      "required": ["type", "authentication"],
      "properties": {
        "type":             { "type": "string", "enum": ["human", "agent", "system"] },
        "authentication":   { "type": "string", "enum": ["required", "optional", "none"] },
        "authorized_roles": { "type": "array", "items": { "type": "string" } }
      }
    },
    "inputs":       { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
    "outputs":      { "type": "array", "items": { "$ref": "#/$defs/parameter" } },
    "evidence":     { "type": "object" },
    "side_effects": { "type": "object" },
    "risk_class": {
      "type": "string",
      "enum": ["low", "medium", "high", "critical"]
    },
    "required_approvals": { "type": "array" },
    "evals":              { "type": "object" },
    "deprecation": {
      "type": "object",
      "required": ["status"],
      "properties": {
        "status": {
          "type": "string",
          "enum": ["incubating", "validated", "certified", "deprecated"]
        }
      }
    }
  },
  "$defs": {
    "parameter": {
      "type": "object",
      "required": ["name", "type"],
      "properties": {
        "name":     { "type": "string" },
        "type":     { "type": "string" },
        "required": { "type": "boolean" }
      }
    }
  }
}

9.Valid example#

The following contract is a complete, well-formed, conforming Skill Contract for a clinical intake skill. It is a separate example from Section 6 and is provided so that implementers can validate their tooling against more than one shape. All identifiers and email addresses use reserved test domains.

Example 2 — Conforming Skill Contract (clinical intake)

# innorve-skill-contract v0.1
schema: innorve.skill-contract.v0.1
skill:
  id: clinic.intake.symptom-triage-summary
  name: Symptom Triage Summary
  version: 0.4.1
  owner: clinical-informatics@example-clinic.test
  description: |
    Given a patient-reported symptom narrative, produces a structured
    summary for the on-call clinician's review queue. Does not assign
    a diagnosis, schedule care, or message the patient.

caller:
  type: agent                  # invoked by the intake orchestrator
  authentication: required
  authorized_roles: [intake-orchestrator]

inputs:
  - name: patient_narrative
    type: string
    required: true
    sensitivity: phi
    max_length: 8000
  - name: encounter_id
    type: string
    required: true
    sensitivity: phi
  - name: locale
    type: string
    required: false
    default: en-US

outputs:
  - name: structured_summary
    type: object
    schema_ref: schemas/triage_summary.v2.json
    required: true
  - name: red_flag_indicators
    type: array
    items: string
    required: true
  - name: confidence
    type: number
    min: 0.0
    max: 1.0
    required: true

evidence:
  required:
    - input_hash               # hash of de-identified narrative
    - model_invocation_id      # vendor-side request identifier
    - reasoning_trace          # ordered list of intermediate spans
    - red_flag_rule_trace      # which red-flag rules evaluated
  format: innorve.evidence.v0.1
  retention_days: 2190         # 6 years

side_effects:
  external_calls:
    - service: vendor-llm-inference
      data_sent: [redacted_narrative, locale]
      idempotent: false
  writes:
    - clinical_review_queue
    - audit_log
  does_not:
    - assign_diagnosis
    - schedule_appointment
    - message_patient
    - modify_chart

risk_class: high
required_approvals:
  - reviewer: clinical-safety-officer
    when: deployment_to_production
  - reviewer: privacy-officer
    when: risk_class_change_proposed
  - reviewer: clinical-safety-officer
    when: input_or_output_schema_change

evals:
  reference: evals/symptom-triage-summary.v1.evals.yaml
  required_pass_rate: 0.97
  regression_tests: 24

deprecation:
  status: validated
  sunset_date: null

10.Invalid examples#

The following contracts are not conforming. Each example is accompanied by the conformance violation and the corrective action. A conforming validator MUST report each violation described below.

10.1Missing REQUIRED field#

The following contract omits the risk_class field. Because risk_class is REQUIRED at the top level of every contract, the document is not conforming.

Example 3 — Missing risk_class

schema: innorve.skill-contract.v0.1
skill:
  id: support.classifier.tier1-routing
  name: Tier-1 Support Routing
  version: 0.2.0
  owner: support-platform@example-saas.test
  description: Routes inbound support tickets to the correct queue.

caller:
  type: system
  authentication: required

inputs:
  - name: ticket_payload
    type: object
    required: true

outputs:
  - name: target_queue
    type: string
    required: true

evidence:
  required: [routing_decision_trace]
  format: innorve.evidence.v0.1
  retention_days: 365

side_effects:
  writes: [routing_audit_log]
  does_not: [auto_close_ticket, notify_customer]

# risk_class is missing.

deprecation:
  status: incubating

10.2Wrong type or out-of-enum value#

The following contract sets risk_class to the string "very high". This value is not a member of the risk_class enum and the document is therefore not conforming.

Example 4 — Out-of-enum risk_class value

schema: innorve.skill-contract.v0.1
skill:
  id: support.classifier.tier1-routing
  name: Tier-1 Support Routing
  version: 0.2.0
  owner: support-platform@example-saas.test
  description: Routes inbound support tickets to the correct queue.

caller:
  type: system
  authentication: required

inputs:
  - name: ticket_payload
    type: object
    required: true

outputs:
  - name: target_queue
    type: string
    required: true

evidence:
  required: [routing_decision_trace]
  format: innorve.evidence.v0.1
  retention_days: 365

side_effects:
  writes: [routing_audit_log]
  does_not: [auto_close_ticket, notify_customer]

risk_class: very high          # invalid: not a member of the enum

deprecation:
  status: incubating

10.3Logically inconsistent contract#

The following contract declares risk_class: critical but omits required_approvals. Because required_approvals is CONDITIONAL on a risk_class of high or critical, this combination is not conforming.

Example 5 — Critical risk class without required approvals

schema: innorve.skill-contract.v0.1
skill:
  id: bank.payments.wire-release-decision
  name: Wire Release Decision
  version: 1.0.0
  owner: payments-engineering@example-bank.test
  description: |
    Given a pending wire instruction, returns whether the wire should
    be released, held for review, or rejected.

caller:
  type: agent
  authentication: required

inputs:
  - name: wire_instruction
    type: object
    required: true
    sensitivity: confidential
  - name: counterparty_profile
    type: object
    required: true
    sensitivity: confidential

outputs:
  - name: decision
    type: enum
    values: [release, hold_for_review, reject]
    required: true

evidence:
  required: [policy_trace, risk_score_breakdown]
  format: innorve.evidence.v0.1
  retention_days: 1825

side_effects:
  writes: [payment_decision_log]
  does_not: [submit_wire_to_network]

risk_class: critical           # critical risk declared...
# ...but required_approvals is absent.

deprecation:
  status: incubating

11.Versioning#

11.1Semantic versioning#

The specification follows semantic versioning of the form MAJOR.MINOR.PATCH. The current version is 0.1.0. Pre-stable versions in the 0.x.y series MAY introduce breaking changes between minor revisions; stable versions (1.0.0 and later) MUST NOT.

11.2PATCH versions#

PATCH versions are limited to editorial fixes that do not change the schema or the meaning of any field. Implementations need not update to consume contracts authored against a newer PATCH version of the same MINOR series.

11.3MINOR versions#

MINOR versions introduce backward-compatible additions: new optional fields, new permitted enum values, new sub-objects. Conforming contracts authored at v0.1.x remain conforming at v0.2.x. Implementations SHOULD ignore unknown fields without error when consuming contracts from a future MINOR version of the same MAJOR series.

11.4MAJOR versions#

MAJOR versions are reserved for breaking changes — removals, renames, type changes, semantic shifts — and are expected to be rare. A MAJOR version increment SHALL be preceded by at least 12 months of community deprecation notice published against the prior MAJOR version. Implementations MUST error when consuming a contract from an unknown MAJOR version, because semantics may have changed in incompatible ways.

11.5The schema field#

The schema field in every contract MUST declare the version it was authored against, in the form innorve.skill-contract.vMAJOR.MINOR. Tooling that consumes a contract without a schema field MAY treat it as v0.1 for backward compatibility but SHOULD warn. Tooling SHOULD warn — not error — on consumption of a contract from a future MINOR version of the same MAJOR series.

12.Security and governance considerations#

12.1Contracts as security artifacts#

A Skill Contract is a security boundary declaration. It states who may invoke the skill, what data it may receive, what external services it may call, and what actions it is bound not to perform. Contracts SHALL be subject to the same review discipline as access control configuration: stored under version control, changed only through reviewed pull requests, and audited at a cadence appropriate to the surrounding environment.

12.2PII and data classification#

Where input fields handle sensitive data, the sensitivity annotation MUST be present and MUST take a value from the set pii, phi, pci, confidential, public. Implementations MUST treat an unannotated field that demonstrably carries sensitive data as a contract violation. The sensitivity annotation is the signal a runtime relies on to apply masking, redaction, retention, and access controls correctly.

12.3Risk class governance#

The risk_class value governs the required approvals, the rigor of the eval suite, and the retention of evidence. A change to the risk_class value of a published contract MUST trigger re-review by the originally named approvers. Lowering a risk class without re-review is a conformance violation; raising a risk class without re-review is permitted but SHOULD also trigger notification.

12.4Evidence retention#

The evidence.retention_days field is governed by applicable regulation. Contracts deployed in regulated environments — including but not limited to SOC 2, HIPAA, the EU AI Act, PCI DSS, and GLBA — MUST set retention values that meet or exceed the longest applicable regulatory requirement. Where multiple regulatory regimes apply, the longer retention obligation governs.

12.5Tampering#

Contracts SHOULD be cryptographically signed by the named owner before deployment to production environments. A runtime that loads a contract for production invocation SHOULD verify the signature against the published key for the named owner and SHOULD refuse to execute under an unverified contract. The signature mechanism is out of scope for this specification.

12.6Innorve Native Mode alignment#

This specification operationalizes Innorve Native Mode tenets 1 and 6. Tenet 1 — Architect before automating — is satisfied by the requirement that every skill be decomposed into a typed, named contract before invocation. Tenet 6 — Human accountability before agent autonomy — is satisfied by the skill.owner field, the required_approvals structure, and the conditional approval rules tied to risk_class. A conforming contract makes both tenets enforceable in code rather than implicit in process.

13.Reference implementation#

The /innorve-skill-contract skill in the public Innorve Method repository is the reference implementation of this specification. It walks an architect through authoring a conforming contract interactively, validates the result against the schema in Section 8, and emits a conforming YAML document.

Repository: github.com/Innorve-Inc/innorve-method.

14.Implementations#

This space is intentionally available. If your tool implements this specification, file a Spec Implementation issue at github.com/Innorve-Inc/innorve-method/issues. Verified implementations will be listed here in the next minor revision.

Listings are unranked, unfiltered, and do not constitute endorsement. The list exists so that downstream users can locate one another.

15.Citation#

Cite this specification as:

Innorve Skill Contract Schema, v0.1 (2026).
Innorve Method, IM-04. Innorve Academy.
https://innorve.academy/spec/skill-contract