The skill manifest

The manifest lives at /skill.manifest.json at the top of the package. Required fields:

{
  "schema_version": "1.0",
  "skill_id": "com.example.shoe-rack-organiser",
  "name": "Shoe Rack Organiser",
  "version": "1.2.0",
  "author": {
    "id": "creator_xyz",
    "name": "Jamie Lee",
    "verified_at": "2026-03-10"
  },
  "robot_compatibility": [
    "gera.robot.v1", "generic.humanoid.v2.1+"
  ],
  "categories": ["household/organisation"],
  "locales": ["en-GB", "en-US", "ja-JP"],
  "license": "proprietary",
  "content_ratings": ["3+"]
}

Versioning is semver and strict. Breaking changes require a new major version and a migration note for installed users.

The capability descriptor

The capability descriptor declares what the skill does in a form agents and buyers can reason about:

{
  "capabilities": [{
    "id": "organise_shoes",
    "inputs": {
      "shoes": { "type": "physical-item-list", "min": 1, "max": 10 },
      "rack_location": { "type": "spatial-anchor" }
    },
    "outcomes": {
      "success": "Shoes placed on rack, paired and upright.",
      "partial": "Some shoes placed; others refused (size, safety).",
      "failure": "Unable to complete; rack inaccessible."
    },
    "typical_duration_seconds": 120,
    "human_oversight_recommended": false,
    "network_required": false
  }]
}

The state machine

Skills are formal state machines. Required states:

idle — waiting for invocation.
invoked — started but not yet acting.
acting — physical actions underway.
paused — user or safety-system pause.
refused — skill declined to act (with reason).
failed — error state.
completed — done; outcomes reported.

All transitions are logged and signed. The state machine is declared in the manifest so the runtime can validate correctness statically.

The safety policy

Every skill must declare:

Refusal conditions. What the skill declines to do (e.g. “refuses to handle kitchen knives”, “refuses if a child is within 2m of rack”).
E-stop behaviour. What happens when an e-stop is triggered — where does the robot place any held item, what state is safe to fail into.
Human handoff conditions. When the skill defers to the robot’s owner.
Maximum continuous action time. Hard-stop after N minutes to force a status check.

Runtime contract

Skills execute in a sandboxed runtime with bounded permissions. The runtime exposes a narrow API — motion primitives, perception queries, speech, user prompts — and refuses calls outside the declared capabilities.

Skills cannot spawn processes, touch the filesystem outside their scratch space, open arbitrary network sockets, or persist data outside the skill-state store. Network access is gated by a domain allow-list declared in the manifest.

The signing pipeline

On upload, the skill is built into an archive, hashed, and signed with the creator’s Ed25519 key (registered at creator-account setup). The catalogue stores the signature and the public key. Robots verify the signature before install; a modified skill fails verification.

Signing establishes:

Provenance — this skill was published by this creator.
Integrity — the bytes the user downloaded are the bytes the creator published.
Accountability — if something goes wrong, the chain of responsibility is clear.

Updates and deprecation

Minor-version updates propagate automatically. Major- version updates require explicit user consent. Deprecation goes through a 90-day notice window; end-of-life forces an uninstall with notification.

Tooling

The CLI provides:

geraskills init — scaffolds a new skill.
geraskills validate — checks manifest + state machine + safety policy.
geraskills test — runs against the simulator + fixture suite.
geraskills publish — builds, signs, uploads to catalogue.

Skill API Spec Deep-Dive — Manifest, Capabilities, State Machine, Safety