I keep bumping into the same problem when working with AI agents: some ideas are too big to explain every time.

**TL;DR:** an Agent Glossary gives those big ideas short names, so I can say "use `explore-plan-execute-review`" and the agent loads the full definition only when it sees the name. Want to skip the story and see the code? Go straight to the [implementation for Pi](https://github.com/ruliana/pi-glossary).

By "ideas too big to explain every time", I mean things like a workflow, a team habit, a project-specific acronym, a recurring review style, a weird internal concept that makes perfect sense after three meetings, two Slack threads, and one mildly traumatic production incident.

Humans solve this naturally by creating names for these things. We say “run the release checklist,” “use the migration playbook,” “ask Maria before touching that service,” “this needs the finance-safe version,” or “send it through the QBR flow.” Maybe QBR once meant “Quarterly Business Review,” but now everyone knows it means “that specific bundle of slides, numbers, approvals, and mild spreadsheet suffering.”

Each phrase carries a tiny backpack full of context.

I’ve been experimenting with feeding agents those definitions to see if I can make the communication between us better.

![](/media/01M43VZ01WMQ43WN2PGSR7FXHQ/agent-glossary-teaching-agents-our-shared-language-1.png)

## The Basic Idea

An Agent Glossary is a set of compact names that point to larger meanings. Once the agent knows the definition, we can use the handle in daily work without unpacking the whole concept every time.

Something like this:

> *Use* `explore-plan-execute-review` *to tackle task X.*

That one glossary entry can represent a full agentic workflow. It can include references to subagents that explore, plan, review, what “done” means, and what kind of evidence should be produced.

## Why This Is Useful

The first benefit is *expressive power*. Once we define useful glossary entries, we can compose richer instructions with less friction. Instead of rebuilding the same prompt from scratch, we can snap concepts together like Lego pieces.

The second benefit is *context management*. Definitions do not need to be rediscovered by brute force every time. The agent does not need to infer what we mean from vague hints, old files, or lucky guesses. We define the concept once, then reuse it deliberately.

There is also a token benefit, but I’d be careful with that argument. The glossary entry itself does not magically save tokens. The definition still needs to live somewhere. The real gain comes from avoiding the brute force searching for meaning.

And yes, there is a trap here: a glossary with too many terms loaded upfront becomes noise.

So the glossary probably needs a lazy-loading mechanism. This could work similarly to skills, but with a more deterministic trigger. Instead of relying on the LLM to understand when a definition is relevant, we can retrieve the context when the term appears in the user’s prompt. I imagine a simple regular expression would do the trick quite well.

## A Concrete Example

Imagine we define `explore-plan-execute-review` like this:

> *Spawn a team of subagents to complete a task end to end. Multiple agents using a cheaper model explore the task by reading the codebase, checking GitHub, internal wiki pages, and Slack messages. Then a stronger planning agent creates a plan. A pragmatic plan-reviewer reviews it. Those two agents loop until the plan-reviewer accepts the plan. After that, a team of executors performs the plan in parallel. Finally, a pragmatic reviewer checks the result, and the same loop happens again between the executors and the reviewer.*

Now we can use it simply:

> *Execute task XYZ using* `explore-plan-execute-review`.

For that simple case, a slash command could work just fine:

> `/explore-plan-execute-review task XYZ`

That is useful, simple, and practical. The glossary starts to shine when we compose ideas:

> *The* `explore-plan-execute-review` *workflow is producing results that are too complex. Create specific pragmatic subagents for each step.*

Now we are talking about the workflow itself. We are modifying it, analyzing it, and reusing its internal structure.

The glossary entry has become part of the working language.

## Where Agent Glossaries Get *Really* Interesting

The real power appears when multiple glossary entries interact:

> *Use* `explore-plan-execute-review` *to create a plan to* `tophat` *the* `railway topic` *“user-saved” in a* `cascading way`.

That sentence looks ridiculous without context. Honestly, it looks like someone lost a fight against an enterprise architecture whiteboard.

But inside the right project, each glossary entry could be precise.

The agent knows what `tophat` means. It knows what counts as a `railway topic`. It knows how `cascading way` should affect the plan. The instruction becomes short because the surrounding language is rich.

That is where glossaries become more than prompt shortcuts. They become a shared vocabulary.

## We Already Work Like This

Every company has these compressed concepts: project names, internal jokes, acronyms. These terms are not random jargon, they exist because they increase communication bandwidth. They let people move faster without re-explaining the whole world every time.

My take is that agents can benefit from the same mechanism.

A glossary can include:

1. recurring workflows;
2. project-specific concepts;
3. people we work with, including their roles and preferences;
4. important events inside or outside the company;
5. vendors and what they provide;
6. internal standards, review styles, and decision rules.

## The Context Loading Problem

A team can have hundreds of useful concepts. That does not mean every agent invocation needs to carry all of them upfront. Most of the time, the agent only needs the small slice of vocabulary that matches the current task.

This is where I think Agent Glossaries can borrow from how Anthropic describes skills: progressive disclosure applied to agent context.

The difference is that glossary entries can have very explicit triggers. If the user says `tophat`, the system loads the `tophat` definition. If the prompt mentions `railway topic`, the system brings that context in. No vibes-based retrieval. Just a boring little trigger doing boring little trigger things.

That is why I like the lazy-loading idea here. A regular expression could detect the term and inject the matching definition into the agent’s working context. The glossary can be large while the active context remains focused.

Also, if we load terms only when we mention them, that means their definitions be close to when they are needed in context.

I started experimenting with this strategy in a small project called [`pi-glossary`](https://github.com/ruliana/pi-glossary), which implements this lazy-glossary idea more directly: definitions can live outside the main prompt and be pulled in when their terms appear.

## Final Thought

An Agent Glossary is a small idea, but I think it points to something bigger. As agents become part of our daily work, we will need better ways to teach them the language of the team.

Raw instructions are usefu, prompt templates are useful, project docs are useful. However, a glossary gives the agent something slightly different: a vocabulary that’s not part of its training.

Once you can name a thing, you can reuse it. Once you can reuse it, you can compose with it. Once you can compose with it, you can build more complex behavior.