DSL — Domain-Shared Lexicon

A Claude Code skill that gives the AI the vocabulary you and your team already speak.

When you say "the heat tapped late" and Claude hears it as a temperature reading instead of a furnace operation, the conversation is already broken. DSL is one focused skill that builds and maintains a shared glossary of domain terms, then loads it into Claude's context — per project, and optionally per domain across all your projects.

It does one thing well. It does not build PRDs, write ADRs, do design reviews, refactor your code, or run grilling sessions about plans. There are good skills for those — this isn't trying to be one.

What you get

• A dsl skill that runs in three modes:
  • On demand — /dsl-init, /dsl-update, /dsl-ingest
  • Proactive — Claude flags ambiguity mid-conversation in one short line, never derails
  • Auto at session start — loads ./LEXICON.md if present; matches global domains against the current project and loads only the matching ones
• A LEXICON.md file format: Term | Definition | Aliases to avoid tables, flagged ambiguities, an example dialogue
• Two scopes:
  • Project — ./LEXICON.md applies to one repo
  • Global — ~/.claude/LEXICON.md holds your recurring domains, each tagged with Applies when: signals so a recipe side project doesn't inherit your day-job metallurgy vocabulary

Safety note: every flow ends in a confirmation before any file is written. /dsl-init never silently creates LEXICON.md or CLAUDE.md — you always see the proposed content first.

How matching works (read this before installing)

The skill has two concepts the rest of the README and templates rely on:

Applies when: — each domain section in your global lexicon declares a small set of signals (deps you use, README keywords, file/dir patterns) that tell Claude when this vocabulary is relevant. Think of it as a predicate: "if the current project looks like this, this domain applies."

Strong vs weak signals. Claude only loads a global domain on a strong signal — named library deps that match (e.g., pyfoundry in your pyproject.toml), or two or more keyword hits in the README, or an explicit domain: <name> line in the project. A single matching filename is a weak signal and is ignored on its own. False positives (loading smelting vocabulary into a recipe app) are worse than false negatives.

Project lexicons always apply — if ./LEXICON.md exists, every term in it is in scope for this repo. Conflicts with global definitions resolve in the project's favour.

Why another glossary skill?

Several similar skills exist (grill-me, grill-with-docs, the original DDD ubiquitous-language). They informed this one. The differences:

	DSL	grill-me	grill-with-docs	ubiquitous-language (deprecated)
Scope discipline	Vocabulary only	Plan/design grilling	Glossary + ADRs	Glossary only
Global lexicon, multi-domain	✅ with Applies when: matching	—	—	—
Off-domain protection	✅ silence on side projects	—	—	—
Auto-load via CLAUDE.md	✅ project @import, global Read+filter	—	—	—
User-provided source material	✅ files, URLs, paste	—	—	—
Proactive ambiguity catch	✅ non-derailing	—	partial	—

If you want a plan-stress-test session, use grill-me. If you want a full domain model with architecture decisions, use Matt Pocock's grill-with-docs. If you just want Claude and you to mean the same thing when you say Heat, Order, or Cluster — that's this.

Install

This repo ships skill and command files. Installation is a copy step + a one-time CLAUDE.md edit.

1. Clone the source

git clone https://github.com/p-vbordei/dsl.git ~/src/dsl

2. Copy the skill and commands into your Claude config

mkdir -p ~/.claude/skills/dsl ~/.claude/commands
cp ~/src/dsl/skills/dsl/SKILL.md ~/.claude/skills/dsl/SKILL.md
cp ~/src/dsl/commands/dsl-init.md   ~/.claude/commands/dsl-init.md
cp ~/src/dsl/commands/dsl-update.md ~/.claude/commands/dsl-update.md
cp ~/src/dsl/commands/dsl-ingest.md ~/.claude/commands/dsl-ingest.md

3. Wire CLAUDE.md

For a per-project lexicon, append the snippet from templates/claude-md-snippet-project.md to that project's ./CLAUDE.md. (Strip the leading HTML comment when you paste.)

For a global lexicon, append the snippet from templates/claude-md-snippet-global.md to ~/.claude/CLAUDE.md. (Same — strip the HTML comment.)

You don't have to do step 3 by hand — running /dsl-init will offer to do it for you and show you the snippet before writing.

4. Restart Claude Code

New skills and commands are picked up on the next session. Start a new session in any repo and run /dsl-init.

First time installing a Claude Code skill? Skills live in ~/.claude/skills/<name>/SKILL.md and are auto-discovered. Slash commands live in ~/.claude/commands/<name>.md. No registration needed beyond placing the files.

Quickstart

You:    /dsl-init
Claude: Scope? [project] / [global-new-domain] / [global-add-to-existing]
You:    project
Claude: Source? [interview] / [ingest] / [scan] / [hybrid]
You:    scan
Claude: I read README.md and the directory tree. Candidates: Heat, Tap,
        Charge, Slag, Ingot, Ferroalloy. Heat — your README implies "one
        furnace batch". Confirm?
You:    yes
… (a few more)
Claude: About to write ./LEXICON.md with 6 terms in 1 domain, and append a
        block to ./CLAUDE.md. Show diff? (y/n)
You:    y
…
You:    proceed
Claude: Wrote ./LEXICON.md: 6 terms in 1 domain. CLAUDE.md updated.

From this point forward, Claude reads the lexicon at every session start in this repo and uses your terms instead of inventing its own.

The lexicon format

Tight, opinionated, small enough to actually fit in context. From templates/lexicon-template.md:

## Domain: <name>           # only for the global file

**Applies when:**            # only for the global file
- Project deps include: ...
- README mentions any of: ...
- File extensions present: ...
- Explicit override: a line `domain: <name>` in project CLAUDE.md

### <subgroup>

| Term | Definition | Aliases to avoid |
|------|------------|-------------------|
| **Heat** | One batch of molten metal produced in one furnace cycle. | run, batch, melt |
| **Tap** | The act of opening a furnace to drain a **Heat**. | drain, pour |

### Relationships

- A **Charge** produces one **Heat** per furnace cycle.

### Flagged ambiguities

- `pour` was used for both **Tap** and accidental spill — a spill is a `breakout`.

### Example dialogue

> **User:** What's the carbon target on the next **Heat**?
> **Domain expert:** Under 0.15% — heavy on scrap, light on coke.

Project lexicons drop the ## Domain: wrapper — every term applies. See templates/example-lexicon.md for a full two-domain example.

Commands

Command	Purpose
/dsl-init	Build a new lexicon from scratch (interview / ingest / scan / hybrid)
/dsl-update [term]	Add or refine specific terms
/dsl-ingest <path-or-url>	Extract terms from existing material (docs, transcripts, glossaries)

What this skill does not do

• Generate ADRs, PRDs, design docs, or feature specs
• Refactor code or rename identifiers
• Run plan-grilling sessions
• Document the codebase ("here's how the auth system works")
• Replace CLAUDE.md itself — it appends a small snippet that references the lexicon

If you find yourself reaching for one of those, you want a different skill.

License

Apache License 2.0 — Vlad Bordei bordeivlad@gmail.com