Authoring a Biome

A biome is a folder with a xema-biome.json manifest at its root. Author against the current component contract and validate with the same schema the host uses.

Start with the boundary

Before creating files, decide what the biome owns:

  • one domain or integration;
  • the capabilities it exposes and requires;
  • the Agents, Skills, Workflows, and UI it contributes;
  • whether it needs executable components;
  • its tenancy, isolation, trust, locality, state, resource, and scaling requirements.

If another domain can use the same behavior only through a typed operation, expose a capability. Do not import the other biome's implementation.

Typical layout

text
1customer-operations/
2  xema-biome.json
3  agents/
4    operations-coordinator.md
5  skills/
6    incident-triage/
7      SKILL.md
8      references/
9        policy.md
10  workflow-config/
11    handle-incident.yaml
12  deliverable-specs/
13    action-plan/
14  workspace-manifests/
15    operations.workspace.yaml
16  contributions/
17    incident-search.contribution.json
18  api/
19    operations-api/

Only include directories the biome uses. The complete convention-directory table is in the Manifest Reference.

Declare components

Every artifact the platform executes or materializes belongs in xema.components[]. The old xema.ships.apis[] field is not the current contract.

An HTTP service component looks like this:

jsonc
1{
2  "key": "operations-api",
3  "kind": "service",
4  "artifact": { "kind": "oci-image", "path": "api/operations-api" },
5  "entrypoint": { "kind": "oci-default" },
6  "protocol": {
7    "kind": "http",
8    "revision": "v1",
9    "serviceName": "operations-api",
10    "authScopes": ["org", "project"],
11    "exposesCapabilities": ["operations:incident.read@1"]
12  },
13  "scheduler": "platform",
14  "executionModes": ["isolated"],
15  "requirements": {
16    "tenancy": { "allowed": ["org", "project"], "tenantContext": "verified" },
17    "isolation": { "minimum": "container" },
18    "trust": { "minimum": "verified" },
19    "locality": { "allowed": ["cloud", "customer-private"] },
20    "state": {
21      "kind": "durable",
22      "scope": "org",
23      "persistence": "database",
24      "consistency": "strong",
25      "tenantFencing": "required"
26    },
27    "resources": { "minimum": { "cpu": "100m", "memory": "64Mi", "ephemeralStorage": "64Mi" } },
28    "runtime": { "kind": "node", "versionRange": ">=22 <25" },
29    "io": { "ingress": "http", "egress": "platform", "rawBody": false, "devices": [] },
30    "scaling": {
31      "mode": "horizontal",
32      "concurrency": { "handling": "parallel", "maximumPerInstance": 16 },
33      "readiness": { "kind": "protocol", "initialDelaySeconds": 0 },
34      "drain": { "kind": "graceful", "maximumSeconds": 30 },
35      "hints": { "cpu": "latency", "memory": "steady", "startup": "fast" }
36    }
37  }
38}

Use components[].artifact.path as the source of truth for the source or artifact location. Do not infer it from a component key.

Add Agents and Skills

Agents are listed under xema.agents[] and authored in agents/. The roster and files are cross-validated.

A Skill is a folder bundle whose only strict file is SKILL.md. References, scripts, assets, and recursive sub-skills stay inside the bundle and are mounted as a unit.

Agents and Skills are independently versioned resources. The same published Agent can run in a Workflow or an Interactive Session.

Add contribution envelopes

Typed single-file contributions live under the configured contribution directory:

json
1{
2  "kind": "capability",
3  "id": "incident-read",
4  "manifest": {}
5}

The kind is a closed contract. A declared enum value is not automatically proof that a public ingestion path exists; consult Contribution Kind for the generated current catalogue and ingestion status.

Declare permissions honestly

List every capability the biome can request and provide a human-readable reason. A declaration is input to install consent and runtime arming; it is never a way to bypass a grant.

Prefer narrow, provider-neutral operations. Separate read, propose, approve, and mutate capabilities where the risk differs.

Validate and publish

Use the biome CLI validation and lint commands available in your installed Xema SDK. Validation must cover:

  • manifest schema;
  • component requirements;
  • Agent roster and file parity;
  • Skill entry files;
  • Workflow and deliverable schemas;
  • contribution envelopes;
  • capability-ref grammar;
  • dependency and boundary rules.

Publish production biomes as immutable, signed artifacts. Keep mutable workspace sources in development and sandbox environments.

Previous: ← Concepts Next: Store →