Semantic Grammar

Define the meaning underneath your product, before anyone opens a design tool or writes a line of code.

Semantic Grammar is a structured interview skill for AI agents. It helps you map the objects, actors, states, and conflicts that persist across every surface of a system: the semantic layer that makes or breaks design and engineering decisions downstream.

npx semantic-grammar

Then open your AI agent and run:

/semantic-grammar

What it does

The skill runs a guided interview across five sections:

1. The system — what it is, not what it looks like
2. Actors — agents with distinct motivations, not personas
3. Objects and states — what persists, and what those states mean to each actor
4. Signals — the forces that shape how meaning reaches its audience: gravity, tempo, intimacy, authority, reversibility
5. The core — one sentence that survives a complete rebuild

At the end, the agent writes a semantic-grammar.md context document to your project. Share it before any UI work, any architecture decision, any agent context. It is more stable than any artifact built from it.

Why

Interfaces are getting smarter, but most practice still starts with screens or schemas. What holds across every adaptation, every surface, every context is not a component or a database table. It is the meaning underneath: what the system is about, who it serves, and where their interests collide.

That layer needs its own grammar.

Supported agents

| Agent | Install location | | --- | --- | | Claude Code | .claude/commands/semantic-grammar.md | | Cursor | .cursor/rules/semantic-grammar.md | | Gemini CLI | .gemini/semantic-grammar.md | | VS Code Copilot | .github/semantic-grammar.md |

The CLI detects which agents are present and installs accordingly. If none are detected, it asks.

Review mode

Already have a semantic-grammar.md? Run:

/semantic-grammar review

The agent reads your document, looks at the current product, and reports where expression has drifted from meaning.

The essay

Semantic Grammar is a 3,000-word essay on why meaning is the stable layer in adaptive systems, and what that demands from everyone who builds products and systems.

stoll.studio/semantic-grammar

MIT © Christophe Stoll