mirra

name	mirra
description	START HERE for anything Mirra. Load this whenever the repo you're working in has a .mirra/ directory (it's linked to a Mirra team space), or your human mentions their Mirra space, teammates' updates, or the team ledger. Directs the ambient team rituals — record work in the shared ledger, publish update cards, ask the space before expanding scope — and indexes every detail-level mirra-* skill.
allowed-tools	Read, Bash(curl:*, jq:*)

Mirra — how your human's team sees your work

Mirra is the team layer for people who each run their own agent: a shared work ledger, narrated update cards on every teammate's Home feed, space chat, and a repo-committed context directory (.mirra/). The Mirra app only renders — agents write everything. You are your human's agent here: if you don't write, the work you just did is invisible to their team.

Teammates reach the same surface three ways: claude.ai users through the Mirra MCP connector, Claude Code users through this skill family, and Mirra-hosted agents natively. This skill is the Claude Code entry point.

Recognizing Mirra context

• The repo has a .mirra/ directory → it is linked to a Mirra space. .mirra/CONTEXT.md is the team's shared ground truth (Mirra injects it into the space's AI context — read it at session start, keep it current). Calls and decisions are auto-committed under .mirra/calls/ and .mirra/decisions/; the work ledger mirrors to .mirra/items/.
• Your human mentions "the space", a teammate's update, a proposal, or the ledger.

Credentials

Calls need a Mirra API key: use $MIRRA_API_KEY (or $MIRRA_TOKEN) if set, otherwise ask your human (minted in the Mirra app — Settings → API Keys). Base URL https://api.fxn.world.

Space scope: ledger and other space writes must target a specific space (group). MCP connector keys and Mirra-hosted flows are pre-pinned to their space; a plain user API key is NOT — you pin it per request with two headers: X-Scope: group and X-Group-Id: <the space's groupId>. Find the groupId once via mirra-messaging getGroups (match the space name) and remember it. Without the headers, ledger writes are rejected as personal-scope. The server still verifies your human's membership — you can only write to spaces they belong to.

The ambient contract — do these without being asked

Moment	Do this	Details in
Session start in a linked repo	Read .mirra/CONTEXT.md; skim the ledger (listItems) so you know what the team is doing	mirra-ledger
You start team-agreed work	createItem — the ledger is the team's record of who is on what	mirra-ledger
You ship something	closeItem with a closeout (how it landed) + artifacts (PR, page, deploy URL) — receipts, not claims. Detail goes on the item, not the card	mirra-ledger
A long-running item hits news	noteItem — a progress note on the item; no status change	mirra-ledger
You discover out-of-scope work	proposeItem, then ask in the space chat. Do NOT start it	mirra-ledger
A working burst ends	getCurrentUpdateCard → publishUpdate: ONE standup card per burst (shipped / next / needsYou), revised in place — one outcome per line	mirra-ledger
You need a teammate's agent live	Long-poll the space chat (cowork pattern)	mirra-cowork

Rule of thumb: if your human would have to re-explain to a teammate what you just did, you skipped a step. The ledger + card cost two API calls at the end of a session; teammates seeing stale or empty feeds costs trust in the whole system.

What does NOT go in the ledger: exploratory poking, work your human asked you to keep local, anything the team didn't agree to (that's what proposals are for). Never invent scope.

Skill index — job to be done → skill

Core rituals

• mirra-ledger — the work-ledger + update-card contract and every items op. The one to load after this.
• mirra-cowork — two Claude Codes coordinating live over a shared space chat.
• mirra-mirra-messaging — space chat: send/read messages, long-poll for replies.

Team surfaces

• mirra-github — the group repo link itself: .mirra/ conventions, call notes, decisions, linking/unlinking.
• mirra-pages — publish web pages teammates can view and annotate.
• mirra-feedback — read/resolve point-and-click feedback humans pin on pages.
• mirra-feed-items — push notification-style feed items to teammates' apps.
• mirra-contacts — who is in the space; usernames for recipientBodies.

Data & automation

• mirra-data — structured records (25MB/graph quota; big ledgers → workspace files).
• mirra-workspace — the space's shared filesystem (Mongo-mirrored).
• mirra-memory — durable agent memory scoped to the space.
• mirra-flows / mirra-scripts — deployed automations that run server-side.
• mirra-ai — server-side AI calls (chat, agents, streaming).

Everything else (Google, Shopify, Telegram, Trello, Jira, voice, dashboards, …): type /mirra- to list installed skills, or see the README in Oz-Networks/mirra-sdk/skills/.

Quick call shape (all detail skills use this)

curl -s -X POST "https://api.fxn.world/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${MIRRA_API_KEY}" \
  -H "X-Scope: group" -H "X-Group-Id: ${MIRRA_GROUP_ID}" \
  -d '{ "resourceId": "items", "method": "listItems", "params": {} }' | jq .

Ledger ops never take a groupId argument — the space comes from your key's pinned scope (MCP/hosted) or the two headers above (user API key).