Coding agents¶
Files in a folder are not enough: an agent has to be told the layers exist and
how to use them. add does it through the file each agent reads at the start
of a session:
| The agent… | add writes |
|---|---|
reads AGENTS.md (Codex, Cursor, Gemini CLI, and most others) |
a section in the project's AGENTS.md |
is Claude Code, which reads CLAUDE.md |
the same section in CLAUDE.md, when the project has a .claude/ folder or a CLAUDE.md, or with --agent claude-code |
The file is created if missing; the section is replaced — never duplicated —
on the next add, and everything else in the file is kept. --all writes it
into every agent file add knows. Layers installed for the user (--global)
belong to no project, so no file is written.
The Agent Skill¶
For agents that support Agent Skills, this
repository ships one: skills/semantic-layers/. Where the AGENTS.md
section says what to do, the skill teaches how — searching and reading
definitions, writing synalog in a layer, every modelling pattern, every error
message — with an example layer that runs without a database. Install it
with the Agent Skills CLI:
Building your own agent rather than using a coding agent? See Adding layer support to your agent.
What the agent reads¶
<!-- semantic-layers:start -->
## Semantic layers
This project's business definitions are semantic layers in `.agents/layers/`: one
folder per layer, each with `tables/`, `concepts/` and `rules/` — one synalog
`.l` file per predicate, described by its front matter (`name`,
`description`).
- **Answer from them.** Before answering a question about the data, search
the definitions that fit (`uvx semantic-layers search '<regex from the
question>'`), read them, and run them (`uvx semantic-layers run
<layer>/<Name>`: the layer's `layer.toml` names the database). Never
re-derive a definition or write ad-hoc SQL.
- **Write what is missing.** An entity or relationship goes in
`concepts/<Name>.l`, a computation in `rules/<Name>.l`, inside the layer
whose tables it uses: front matter with `name` (the predicate that runs)
and `description`, one `import <folder>.<Name>.<Name>;` per predicate it
uses, an `@OrderBy` (and `@Limit` for a ranking), then the rule.
- **Check before saving**: `uvx semantic-layers check <layer>`.
<!-- semantic-layers:end -->