agentleFS
dikamilodikamilo/dx-workflow/skills/dx-domain/SKILL.md

dx-domain

Skill8 starsChanged 4 months agoMITView on GitHub

Actively sharpen the ubiquitous language in foundation/glossary.md. Fire the instant a domain term clashes with an existing definition, is vague or overloaded (an "account" that might be a Customer or a User), or finally gets pinned down — mid-task, not only when asked. Capture or correct the term, then hand back to the interrupted work.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Guard: Write only foundation/glossary.md.

    line 14
  2. Distinctive:

    Cross-check the code: If what the user says contradicts what the code does, surface it: *"Your code cancels whole Orders, but you just said …

    line 21
  3. Very specific:

    Be opinionated: When several words mean one thing, pick the best and list the rest under _Avoid_.

    line 22

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

dx-domain

The active glossary discipline: challenge a term, sharpen it, and write it to foundation/glossary.md the moment it resolves. Merely reading the glossary for naming is a one-line habit any skill does — this skill is for changing the model, not consuming it. It fires on three triggers during any work:

  • Clash — a term contradicts an existing glossary definition. Call it out at once: "The glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
  • Fuzzy — a vague or overloaded term is in play. Propose one precise canonical term: "You said 'account' — is that the Customer or the User? Those are different things."
  • Resolved — a term gets nailed down during framing/design/implementation. Capture it immediately, before the moment passes.

Guard. Write only foundation/glossary.md. If context/foundation/ doesn't exist, the project isn't scaffolded — say so and suggest /dx-init. Create glossary.md lazily on the first resolved term.

Sharpen before you write (invoke dx-references with knowledge-layer)

Load knowledge-layer for the glossary entry shape and the standards/lessons/glossary distinctions. Then force precision:

  • Invent a concrete edge-case scenario that probes the boundary between two concepts and makes the user commit. Vague terms survive in the abstract and break on specifics.
  • Cross-check the code. If what the user says contradicts what the code does, surface it: "Your code cancels whole Orders, but you just said partial cancellation exists — which is right?"
  • Be opinionated. When several words mean one thing, pick the best and list the rest under _Avoid_.

Write inline, glossary-only

The moment a term resolves, add or edit its entry in foundation/glossary.md using the knowledge-layer entry shape — definitional, domain-only, one or two sentences (what it IS, not what it does). Don't batch. Skip general programming concepts (timeouts, retries, error types) — only terms unique to this project's domain belong.

The file is a glossary and nothing else: never a spec, a scratch pad, or a home for implementation decisions. Only dx-domain and dx-domain-discover write it.

Done when

The resolved term is written to foundation/glossary.md (clash corrected, fuzzy term made canonical, or new term captured). Because this fired mid-task, suggest returning to the interrupted work — don't silently resume it and don't auto-chain:

Glossary updated: foundation/glossary.md  (<Term>)
Back to: <the task this interrupted>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.