Write Your First OpenClerq Skill: One Markdown File

OpenClerq ships with no skills at all. That is deliberate — the core makes no assumptions about your profession or your country — but it does mean the agent does nothing useful until you teach it something.

A skill is one SKILL.md file: YAML frontmatter the gateway reads, then Markdown instructions the model reads. This tutorial writes one, loads it, and proves the routing works without spending a single token.

The file

Put it under the directory the gateway watches (CLERQ_SKILLS_DIR, or the workspace default). The frontmatter is the part the gateway parses; everything after it is instruction text passed to the model when this skill is selected.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36---name: "Expense Check"slug: "expense-check"version: "2026.1"# The gateway matches these against the text of a /task call. Keep them# specific: two skills that both trigger on "invoice" will fight.triggers: ["expense", "receipt", "reimbursement"]moduleType: "calc"domains: ["admin"]# Optional, but worth writing: it is what makes the skill's output# structured rather than prose you then have to parse again.inputSchema:  type: object  required: [amountMinor, currency, category]  properties:    amountMinor: { type: integer }    currency:    { type: string, minLength: 3, maxLength: 3 }    category:    { type: string }outputSchema:  type: object  properties:    withinPolicy: { type: boolean }    reason:       { type: string }---Check one expense line against the policy in `rules/policy.md`.Rules:- Do the arithmetic with the calculation tool. Never compute a figure yourself.- If the category is missing from the policy, return withinPolicy: false with a  reason saying the category is unknown. Do not guess a limit.- Quote the specific policy line you relied on, so a person can check you.

Load it and check the routing

The gateway loads every SKILL.md it finds under the skills directory. POST /task then matches your message against the triggers and picks a skill. `dryRun: true` runs that matching and any calculation but never calls the model — which makes it the right way to test routing, since it is free and repeatable.

$ curl -s -H "Authorization: Bearer $(cat ~/.clerq/gateway-token)" http://127.0.0.1:18790/skills{"skills":[{"slug":"expense-check","name":"Expense Check","version":"2026.1"}]}# dry-run: routes and calculates, but never calls the model$ curl -s -X POST http://127.0.0.1:18790/task \>   -H "Authorization: Bearer $(cat ~/.clerq/gateway-token)" \>   -H "Content-Type: application/json" \>   -d '{"message":"is a 40 EUR client lunch receipt within policy?","dryRun":true}'{"dryRun":true,"matchedSkill":"expense-check", "intent":"skill","extracted":["40"], "llm":{"called":false,"reason":"dryRun"}}# a message with none of the triggers falls through, as it should$ curl -s -X POST http://127.0.0.1:18790/task -H "Authorization: Bearer $(cat ~/.clerq/gateway-token)" \>   -H "Content-Type: application/json" -d '{"message":"book a meeting room","dryRun":true}'{"dryRun":true,"matchedSkill":null,"intent":"explain"}

From skill to module

A module is just a coherent group of skills, templates and rules — a folder, not a new concept. Once you have three or four related skills, give them a shared directory with the reference material they cite (rules/, templates/) so the instructions can point at real files instead of restating policy inline.

1. 1.Start with the narrowest useful skill. One job, one output shape.
2. 2.Add inputSchema and outputSchema as soon as anything downstream consumes the result.
3. 3.Use dependsOn when one skill genuinely needs another to have run first.
4. 4.Keep policy in files the skill cites, not in the prompt. Policy changes; prompts get forgotten.