/shared-language

The failure this kills

Ask your agent a simple question and you get a paragraph where a word would do. It is not being thorough — it is missing your vocabulary. Every team develops a private language: the words for your customers, your pipeline, your internal processes. Your agent never got that onboarding, so it describes concepts instead of naming them, and names the same thing differently in every file it touches.

Every one of those descriptions costs tokens, time, and misunderstandings — and inconsistent names quietly become inconsistent behaviour.

What it does

Type /shared-language once per project and the agent builds a glossary with you:

• It scans first — code, docs, data, configs — and collects the terms that matter.
• It flags every collision — one thing, two names — and proposes its best definition for each term.
• You settle each one. Facts are the agent’s job to gather; naming decisions are yours to make.
• The result is one file at the project root: every concept, one canonical name, one-line definition.
• From then on the glossary is law — answers, code, file names, questions. One concept, one word. New concept with no name? The agent stops and names it with you before building on it.

When to reach for it

At the start of any project the agent will live in for more than a day — and any time answers feel bloated or naming has drifted. It is not just for code: a finance team’s vendor names, a marketing team’s campaign labels, an ops team’s process steps. Anywhere two people — or a person and an agent — keep talking past each other, the glossary ends it.

Keep entries one line each. A lean glossary gets read; a bloated one gets ignored — the same rule Anthropic gives for context files.

Install

mkdir -p .claude/skills/shared-language
curl -o .claude/skills/shared-language/SKILL.md https://agentropic.ai/skills/shared-language/SKILL.md

Works with Claude Code and any agent that supports the SKILL.md convention.

Credits

The idea is Eric Evans’ ubiquitous language (Domain-Driven Design, 2003). Matt Pocock’s domain-modeling skills (MIT) brought it to agent workflows. Our implementation is an original rewrite of the discipline for any team — not just engineering.

---
name: shared-language
description: Build a shared glossary with your agent — scan the project, settle the terms, then use them everywhere.
---

Before we go further in this project, build our shared language.

Scan the project first — code, docs, data, configs. Collect the terms that matter: the entities, the states, the processes, and every place where two names exist for one thing.

Then interview me, one term at a time: propose your best definition, flag every collision, and let me settle each one. Facts you can read are yours to gather; naming decisions are mine to make.

Write the result to a glossary file at the project root — one concept, one canonical name, one definition each — and keep it current as the project evolves.

From then on, the glossary is law: use it in your answers, your code, your names, your questions. One concept, one word. If I use a term loosely, correct me. If a new concept appears without a name, stop and name it with me before building on it.

<!-- Original implementation by Agentropic (agentropic.ai/skills/shared-language).
     Inspired by the ubiquitous-language idea (Eric Evans, Domain-Driven Design),
     brought to agent workflows by Matt Pocock's domain-modeling skills (MIT, github.com/mattpocock/skills). -->