Example: Hello Biome

Complexity: Starter Contributions: one workflow, one skill Capabilities required: kb:page.write@1

A minimal biome that runs a single workflow and uses a skill. No backend service, no frontend contributions, no connectors. The smallest possible thing that works end-to-end.

Goal

When triggered manually, the biome runs a workflow that uses the hello-skill to draft a short greeting and saves it to the knowledge base.

File layout

text

1hello-biome/
2  xema-biome.json
3  skills/
4    hello-skill/
5      SKILL.md
6  workflow-config/
7    hello.yaml

`xema-biome.json`

json

1{
2  "name": "@acme/hello-biome",
3  "version": "0.1.0",
4  "xema": {
5    "id": "hello-biome",
6    "displayName": "Hello Biome",
7    "description": "A minimal starter biome for learning the authoring model.",
8    "scope": "platform",
9    "target": "server",
10    "requiresCapabilities": ["kb:page.write@1"],
11    "permissions": {
12      "defaultProfile": "internal-agent",
13      "hints": [
14        {
15          "capability": "kb:page.write@1",
16          "reason": "Saves the generated greeting to the knowledge base.",
17          "riskTier": "low"
18        }
19      ]
20    }
21  }
22}

The skill and workflow are not declared anywhere — they are discovered from the skills/ and workflow-config/ convention directories by on-disk presence.

`skills/hello-skill/SKILL.md`

markdown

1---
2name: hello-skill
3description: Teaches the agent to write a friendly, personalized greeting for a given audience.
4---
5
6# Hello Skill
7
8## Audience
9
10You are writing for a technical audience that values clarity and brevity.
11
12## Greeting format
13
14- One sentence of welcome.
15- One sentence describing what Xema can help them accomplish.
16- Sign off with the org name.
17
18## Example
19
20> Welcome to Acme's Xema workspace.
21> Here you can run code reviews, generate specs, and collaborate with your AI team.
22> — Acme Engineering

`workflow-config/hello.yaml`

yaml

1apiVersion: workflow/v1alpha1
2kind: Workflow
3metadata:
4  name: hello-workflow
5  slug: hello-biome/hello
6spec:
7  trigger:
8    kind: manual
9  inputs:
10    audienceName:
11      type: string
12      description: "Name of the audience to greet"
13  steps:
14    - name: draft-greeting
15      kind: agent
16      with:
17        skill: hello-skill
18        prompt: |
19          Draft a greeting for: {{ inputs.audienceName }}
20      output:
21        as: greeting
22    - name: save-to-kb
23      kind: capability
24      with:
25        ref: kb:page.write@1
26        input:
27          title: "Greeting for {{ inputs.audienceName }}"
28          content: "{{ steps.draft-greeting.greeting }}"

Run it locally

bash

1# 1. Run the workspace boundary checks
2xema biome lint
3
4# 2. Run your workspace biome against a platform — local sources always win
5xema biome dev

Then trigger the hello-biome/hello workflow from the Workflows page with audienceName: "Engineering Team" and watch the greeting land in the knowledge base.

What to change for a real biome

Add connector:scm.create-pull-request@1 to xema.requiresCapabilities (with a matching permissions.hints[] entry) and use it in a step.
Add an agent definition under agents/<slug>.md and declare it in xema.agents[].
Extend SKILL.md with richer reference material relevant to your domain.

Previous: ← Examples Overview