ai:skills › diesel2 · version 1 · 2026-09-25 04:03 UTC
EditMarkdown
name
diesel2
description
Use the d2 (diesel2) prototype at d2.aidieselapps.com from an AI assistant: read and write wiki topics, memories and skills, define a domain with $class, create and query objects, make stylesheets, write and maintain specifications, keep to-do lists and a project log of design decisions, and try expressions. Use whenever the user mentions d2, diesel2, their d2 wiki, or asks to save notes, memories, classes or objects there, or to change how d2 looks.

diesel2: using the d2 prototype from your AI

d2 is a wiki, a domain model and an object store behind one HTTP API at https://d2.aidieselapps.com/api/v2. This skill is what an AI assistant needs in order to work with it. Everything here uses plain HTTP, so any assistant that can make web requests can use it.

Install

  1. Network. Let your AI reach d2.aidieselapps.com over HTTPS. In Claude, allow the domain in the network settings of your project or workspace (*.aidieselapps.com covers it).
  2. Token. Reads are open; writes need a bearer token. Get it from whoever runs the prototype, and give it to your AI in the chat when it asks. Never save the token in a topic, a memory or this skill.
  3. This skill. Download it as markdown from https://d2.aidieselapps.com/api/v2/topics/Skill:diesel2, save it as diesel2/SKILL.md, and add it to your AI as a skill (in Claude, upload it as a custom skill). The copy here in the wiki is the source; download it again when it changes.
  4. Try it. Ask your AI to "list the d2 topics" and then "open the Welcome topic".

Calls

Every write sends Authorization: Bearer <token>. JSON goes in and out, except topic bodies, which are plain markdown.

B=https://d2.aidieselapps.com/api/v2
curl -s $B/health                                   # version, topic count

# topics: the wiki (Topic), and Spec, Memory and Skill topics
curl -s "$B/topics"                                  # list; ?category=Memory or Skill filters
curl -s "$B/topics/Welcome"                          # markdown; ?format=json for {name, text, ver, updated}
curl -s -X PUT "$B/topics/Frostline" -H "Authorization: Bearer $T" --data-binary @Frostline.md
curl -s -X DELETE "$B/topics/Memory:old-note" -H "Authorization: Bearer $T"

# the domain (read-only: classes are declared in topics)
curl -s "$B/domain/overview"                         # classes, links, enums, errors, warnings
curl -s "$B/domain/cat/Company,Property"             # full definitions; cat/* for all

# objects
curl -s "$B/dom/val/Company"                         # list {total, class, data}
curl -s "$B/dom/val/Company?query=stage%20is%20%22Producer%22"
curl -s "$B/dom/val/Company:FLR"                     # one object; 404 if missing
curl -s -X PUT "$B/dom/val/Company:FLR" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @flr.json
curl -s -X POST "$B/dom/val/Company" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @new.json   # 409 if the key exists

# stylesheets: the built-ins and the Style topics
curl -s "$B/styles"

# OpenSpec topics as an openspec/ tree: {files: [{path, content, topic, check}]}
curl -s "$B/openspec"

# expressions (open, no token)
curl -s -X POST "$B/diesel/expr" -H "content-type: application/json" -d '{"source":"[1, 2, 3] map (x => x * 2)"}'

Topics and categories

Memories: what you remember about the user

Keep what you learn about the user in Memory: topics instead of only in your own memory, so the user can read and correct it at /topics?category=Memory.

Specifications: AiSpec or OpenSpec topics

The specifications you work on with the user live in d2, not only in the chat, so the user can read and correct them at /topics?category=AiSpec (ai:specs lists both formats).

Free-form (AiSpec:)

OpenSpec (OpenSpec:)

Both formats

To-dos: keep the open items

Keep a ToDo: topic per project (for example ToDo:diesel2) for the open items, so nothing agreed-but-deferred lives only in a chat. The user sees them at /topics?category=ToDo.

Project log: record design decisions

Keep a Log: topic per project (for example Log:diesel2) and record every design decision in it as it's agreed, so the user has a dated history of what was decided and why. The user reads it at /topics?category=Log.

## 2026-09-24 · Int is Java's long

- **Decided by:** Razie
- **Decision:** `Int` is a signed 64-bit integer that wraps on overflow.
- **Why:** The final code may be generated in Java, and the two must agree.
- **Where:** [[Diesel2Expressions]]; proto1 v0.3.2

Skills

Skill: topics are instructions like this one, in the SKILL.md format: frontmatter with name and a description that says when to use it, then the steps. The user can install any of them in their AI the way section "Install" describes.

Domain and objects

Classes are declared in Spec topics (Spec:<name>, like the sample mining-domain), on lines that start with $ (or inside a ```diesel fence). Saving the topic reloads the domain.

$enum Stage (explorer, developer, producer)

$class Company (
  @key ticker: String,
  @label name: String,
  stage: Stage = explorer,
  listedOn: Date?,
  properties: <>Property*,
  headquarters: Address?,
) @group("Corporate")

$object Company:FRST (ticker = "FRST", name = "Frost Inc", stage = "developer")

Make a stylesheet

A stylesheet is a Style: topic. When the user wants a different look (colours, fonts, the logo text), write one:

---
name: yahoo
description: Dark green with magenta text; the logo says YAHOO
brand: YAHOO
---

# yahoo

```style
--paper: #0b3d1e
--card: #114d2a
--ink: #ff3fd2
--soft: #e8a2dc
--line: #226b3f
--indigo: #ff85e8
--indigo-bg: #2b1d36
--slate-bg: #0f4526
```

Rules and stories

Behaviour lives in Spec: topics as rules; Story: topics send messages and check the results. The engine runs them strictly in order. Examples: hello / hello, order / order, alerts / alerts.

$when order.discount (subtotal: Float, member: Boolean) if (member) {
  payload = subtotal * 0.10
}

Expressions

The expression language is the one in the fiddle (/fiddle). It reads like English, with the usual symbols as aliases: and, or, not, is, is not, in, is a Number, is defined, is empty, ??, matches /regex/, if … then … else, plus map, filter, fold (acc = 0) (x => …), indexBy and mkString. Int is a 64-bit integer that wraps on overflow, like Java's long, and / always gives a Float.

Things to know

Related: company-notes, domain-modelling, and the pattern this comes from, Diesel2AI.