uselemma Lemma Artifacts
You are recording, in Lemma, what the AI agents in this codebase are for.
Lemma detects failures in production agents by reading their traces. It reads them better when it knows what the agent was supposed to do. That knowledge normally accrues from traces over time, which means the earliest traces are judged with no context at all. This skill front-loads it from the source the customer already has: their own code.
Two things follow from where you are standing, and they govern everything below.
The code tells you intent, not behaviour. You are reading what the authors meant to build. Only traces show what actually happens. Never state a code-derived claim as an observation.
Nothing is written without the user saying yes to specifics. You are about to put words in their vendor's mouth about their own system. They get to read those words first, every time.
Core rules
- Read Lemma's current state before proposing anything. Call
list_project_artifactsfirst, always — including when you expect it to be empty. What is already recorded changes what is worth adding. - Never call a write tool before the user has approved that specific
content in this conversation.
write_learn_agent_artifact_version,upload_project_artifact,update_project_artifactanddelete_project_artifactall wait for an explicit yes. - Itemize the claims in the confirmation. "Write 3 artifacts?" is not a confirmation. Name the agent, state the claims, and say which file each would land in. See references/record.md.
- Never modify the user's code. You are reading their repository to describe it. No edits, no new files, no reformatting — not even to a README, and not to "fix" something you noticed. Mention it and move on.
- Never touch the key. You reach Lemma with
LEMMA_MCP_API_KEY, which the user sets in the environment you run in. Reference it by name only. Never read, print, echo, or write its value into any file, tracked or not, and never ask the user to paste it into this conversation. A placeholder line such asLEMMA_MCP_API_KEY=in an env example is fine. If it is missing, see When Lemma refuses the connection. - Never call
regenerate_project_artifacts. That starts Lemma's own trace-driven learning run, which is a different thing costing real time and money, and it is not how this skill writes. - Say what convinced you. Every proposed claim cites the file that supports it. A claim you cannot point at is a claim you should drop.
- Keep tool names exactly as written here so transport mappings stay valid.
Two kinds of artifact, and they are not interchangeable
Lemma stores two things and the word "artifact" is used loosely for both. They behave differently and picking wrong loses information.
| Agent understanding | Project context files | |
|---|---|---|
| Holds | how the agent works | rules it must obey, facts no trace shows |
| Written by | Lemma's learning runs, and you | the customer, and you |
| Rewritten by Lemma | yes, from observed traces | never |
| Tools | write_learn_agent_artifact_version |
upload_project_artifact, update_project_artifact, delete_project_artifact |
| Contract | references/agent-artifact-contract.md | references/project-context-contract.md |
The test for which one a finding belongs in: would a run that disagreed with this statement be worth reporting? If yes it is a rule — a spend cap, a mandatory escalation, a never-do — and it goes in a project context file, where Lemma will not quietly revise it to match what the traces show. If no it is a description, and it goes in the agent understanding document.
Put a rule in the wrong place and a later learning run can normalise it away against the very traces that violate it.
Workflows
| Step | When | Reference |
|---|---|---|
| Discover | Find the real agents, tell them from examples and dead code, settle their names | references/discover.md |
| Record | Read current state, propose, confirm, write, report | references/record.md |
| Hand off | After the closing report, offer tracing when the settled target agent is not instrumented — written or declined | references/tracing-handoff.md |
Read all three before acting. Run them in that order.
When Lemma refuses the connection
A 401 from any Lemma tool means the key behind LEMMA_MCP_API_KEY is
missing, expired, or revoked. It is a thing for the user to fix, never a thing
to work around.
Stop there. Write nothing, offer nothing, and tell the user to set
LEMMA_MCP_API_KEY in the environment this agent runs in, then run you again.
A key comes from the Describe your agent step in Lemma onboarding, or from
Settings → API keys in the dashboard.
Do not ask them to paste the key to you. Do not read it back out of a file or the environment to check it. Do not retry the call until they say it is set.
When this is not the right skill
- The user wants tracing installed, or traces are not arriving: hand off to
lemma-tracing. Do not install the SDK yourself. The one time this skill raises tracing on its own is the offer after the closing report (references/tracing-handoff.md): the offer is a question, and the work is stilllemma-tracing's. - Traces arrive but are thin or malformed: hand off to
lemma-diagnostics. - The user wants to triage detected issues: that is
lemma-mcp.
This skill does not need traces to exist. Recording specification before the first trace is the point of it, so an empty project is a normal starting state, not a blocker.