# Lemma Artifacts

> Read this codebase and record what its AI agents are for in Lemma. Use when the user asks to tell Lemma about their agent, set up or improve Lemma artifacts or agent context, record what an agent does, describe their agent to Lemma, bring Lemma's understanding up to date with the code, or fix a rule Lemma still has that the codebase no longer enforces. After its closing report it offers to hand off to lemma-tracing when the agent it settled on is not instrumented, whether or not anything was written. Do not use for installing tracing or fixing trace delivery and shape — that is lemma-tracing and lemma-diagnostics.

- Skill: `uselemma/lemma-artifacts` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add uselemma/lemma-artifacts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uselemma/lemma-artifacts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: uselemma (https://skillmd.com/u/uselemma)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uselemma/lemma-artifacts

---


# 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

1. **Read Lemma's current state before proposing anything.** Call
   `list_project_artifacts` first, always — including when you expect it to be
   empty. What is already recorded changes what is worth adding.
2. **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_artifact` and
   `delete_project_artifact` all wait for an explicit yes.
3. **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](references/record.md).
4. **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.
5. **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 as `LEMMA_MCP_API_KEY=` in an env example is fine. If it is
   missing, see [When Lemma refuses the connection](#when-lemma-refuses-the-connection).
6. **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.
7. **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.
8. 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/agent-artifact-contract.md) | [references/project-context-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](references/discover.md) |
| Record | Read current state, propose, confirm, write, report | [references/record.md](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](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](references/tracing-handoff.md)): the offer
  is a question, and the work is still `lemma-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.