IRMA for developers: agents

This page is for anyone who has an AI agent work with IRMA: a coding agent such as Claude Code, your own agent, or an assistant that reads this documentation.

The Claude Code skill

The skill tells Claude Code when and how to use the irma CLI, and which rules apply. To install:

mkdir -p ~/.claude/skills/irma
curl -fsSL https://docs.prudai.com/skills/irma/SKILL.md -o ~/.claude/skills/irma/SKILL.md

For one project, put it in that project’s .claude/skills/irma/. With another agent you can copy its contents into your AGENTS.md or system prompt: it is plain Markdown.

irma guide

The CLI has its own guide for agents: irma guide. It covers the two doors and their keys, the envelope, the dry run on writes, the exit codes and what an agent may not do. The guide always matches the installed version; have an agent read it at the start of a session. The full text is also in the CLI reference.

This documentation for agents

What	Where
Table of contents for language models	/llms.txt
The full text of every public page in one file (NL and EN)	/llms-full.txt
Every page as Markdown	append .md to the slug, for example /en/irma-developers-quickstart.md
The same page as Markdown through content negotiation	curl -H 'Accept: text/markdown' https://docs.prudai.com/en/irma-developers-quickstart/

Pages behind sign-in are deliberately left out of llms.txt and llms-full.txt, and the Markdown version of such a page is only served after sign-in.

Rules for an agent

• Start at the right door. For incidents: irma whoami. For /v1: irma context --json, and read the read scope. With beperkt or geen, an empty list does not mean there is nothing.
• Read the whole envelope. Page until nextOffset is empty, use notIncluded and next, and state the provenance of every number. Do not invent percentiles or amounts.
• Writing is a dry run until --no-dry-run --yes. Read the plan, then confirm.
• Drafts, not direct changes, except when reporting incidents. See Concepts.
• A 403 is the design. Do not work around it and do not ask for a broader key.
• Never pass a key as a flag on the command line. Use an environment variable or irma auth set --stdin.
• Do not copy content from IRMA into tickets, commits or chats outside IRMA. Report at metadata level: counts, status, ids.

MCP server

Later. After the API and the CLI comes an MCP server, so AI clients that speak MCP can use IRMA directly as tools. It uses the same task logic as the API: the same envelope, the same permissions, the same dry run and approval. Until then the CLI with the skill gives an agent the same capabilities.