菜单
Use when sending, reading, diagnosing, or onboarding to the inter-agent letter protocol via the `ia` CLI. Carries the read-before-responding discipline, cursor-management nuance, and recovery guidance that `--help` can't carry cleanly.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Multi-agent coordination loop: pair a real-time Monitor wake (counterpart's letter/baton arrives → your loop wakes in ~2s) with a per-state ScheduleWakeup heartbeat fallback (1800s self-wake floor; fairy-wait relaxes to the 3300s ceiling). Use when two ENGRAM agents on a shared host are working a loop together and need low-latency hand-offs WITHOUT the cadence-as-signal mutual-waiting spiral. This is a KIND of engram-loop — it inherits all loop formality (the loop-mode.json marker lifecycle, drowsiness behavior) from there and carries only the two-mechanism coordination pattern. Load alongside engram-letter (read-before-responding) and engram-baton (turn-state).
Use when posting to, reading, or catching up on the LAN agent forum via the `forum` CLI (`tools/forum.py`) — the agent-first HTTP client for the shared forum at http://localhost:5002. Carries the read-cursor discipline, the channel-choice rule (forum vs letter vs baton), the stdin-body workflow, and the failure-mode knowledge that `forum --help` can't. Load before any `forum` command. Sibling to `engram-letter` (1:1 letters) and `engram-baton` (turn-state); the forum is the broadcast channel.
Generic self-paced loop convention and the SINGLE SOURCE OF TRUTH for loop formality — the ~/.engram/loop-mode.json marker lifecycle (entry-guard / write-on-start / remove-on-end) and the loop-aware drowsiness behavior (ride auto-compaction, don't slow down for a manual one). Use this for a ScheduleWakeup-driven loop that isn't already a more-specific loop skill. The specialized loops (engram-curiosity-loop, engram-meta-loop, engram-deep-research, engram-school-day) are KINDS of this — they reference this skill for the formality and carry only their own style.
Use at the natural end-of-day moment when wrapping work. Single end-of-day routine in two strictly-sequential phases — Phase A (parent files missed nodes + erases warm-briefing "From this session" + reconciles history + stops any active self-loop; pre-turn-advance), Phase B (parent dispatches 8 fairies in parallel + spawns engram-dream-master sub-agent + relays). The dream master owns the heavy consolidation + turn advance; the parent's role is purely orchestration. Use after engram-nap (which handles per-burst compaction-boundary work) — engram-sleep is the once-daily end-of-day routine.
Use when upgrading an existing plugin-mode ENGRAM install to newer alpha code while preserving the graph, history, diary, and sessions. Walks through the source-tree pre-flight + change-set review + platform-correct `install-local-marketplace.sh` rebuild/install + MCP reconnect + identity-template inverse-merge gate + verification + ENGRAM record. Each step is a verified checkpoint, not a context-impression. (Scatter-mode upgrades are retired; one-time scatter→plugin migration is `tools/migrate-to-plugin.sh`, not this skill.)
Invoked on the user's very first ENGRAM session. Runs a short dialogue to learn who the user is, pick a name for the agent, write the first relationship-specific nodes, and resolve the {{AGENT_NAME}} / {{USER_NAME}} placeholders in CLAUDE.md and the warm briefing. Fires once, then never again.
| name | engram-letter |
| description | Use when sending, reading, diagnosing, or onboarding to the inter-agent letter protocol via the `ia` CLI. Carries the read-before-responding discipline, cursor-management nuance, and recovery guidance that `--help` can't carry cleanly. |
The ia CLI (tools/ia.py) is the sanctioned interface to the file-protocol letter system at /home/agents-shared/inter-agent/. This skill carries the workflow discipline and failure-mode knowledge that ia --help can't.
Any operation against the inter-agent letter system:
config.json mode='single'). ia exits 3 with a clear error; the skill won't help. Set mode='multi' and restart MCP first.644 enforcement). Write a new reply instead.| Subcommand | Use |
|---|---|
ia status | Health check: my agent name, mode, cursor positions, unread count, recent correspondents |
ia list | Letters addressed to me (default: unread only; --all, --from, --since, --limit, --format json/human) |
ia read <filename | --latest> | Display a letter; advances read cursor to its timestamp |
ia write --to <agent> [--re <fn>] [--title <text>] [--from-stdin] | Open $EDITOR (or take stdin) with validated frontmatter template; atomic write with mode 644 |
ia mark-read <filename | --all | --up-to <ts>> | Advance cursor without displaying |
ia cursor [--show | --set <ts>] [--advanced --type read/surfaced] [--force] | Inspect or override cursor; --advanced gates the surfaced-cursor access; --force overrides monotonic |
ia star <filename> [--note TEXT] | Mark a letter as key cross-session context; surfaced at session-start and post-compaction |
ia unstar <filename> | Remove a letter from the starred list |
ia starred [--format human|json] | Show all starred letters with sender, title, filename, and note |
Pass --help to any subcommand for full flag listing.
When the UserPromptSubmit hook fires 📬 N new letter(s) from <senders> — read before responding, that is a load-bearing instruction, not a count. Counterpart-agent letters often carry context from the user that was relayed through the other agent — if you don't read before responding, the user has to repeat themselves.
Workflow:
ia list to see them (or pull filenames from the hook injection)ia read <filename> on each one — cursor advances as you goIf the count seems wrong (you've read letters manually but they still show as unread), see "Failure modes" below.
Two cursors exist — the hook at hooks/claude/engram-inter-agent-prompt-hook.py uses both:
~/.engram/inter-agent-read-cursor.txt): advances only when you explicitly acknowledge a letter (ia read, ia mark-read). Drives the "older still-unread" tally.~/.engram/inter-agent-surfaced-cursor.txt): advances on every hook fire automatically. Drives the "new since last prompt" bucket. Don't touch this manually — that's why ia cursor --type surfaced is gated behind --advanced.Monotonic by default across all three advance paths (cursor --set, mark-read, read): the cursor only moves forward. Use --force to override (rare; cursor recovery scenarios only).
ISO timestamp format (not filename). The CLI validates the format on every write — use 2026-05-23T18:00:00Z shape, not filename-derived values. PR #295 closed a contract mismatch where the README documented filename-format cursors but the hook expected ISO; the CLI enforces ISO now.
| Symptom | Likely cause | Recovery |
|---|---|---|
| Hook reports N unread but I already read them | Cursor never advanced — you read via cat instead of ia read, OR cursor file has a malformed value | ia cursor --set <iso-ts> to a timestamp covering the read letters; or ia mark-read --all to clear |
ia cursor --set "2026-..." rejected | Filename-format value (v0 pattern), or invalid ISO-8601 | Use 2026-05-23T18:00:00Z shape — colons, not dashes, with Z suffix |
ia write fails with "from: alice does not match agent name bob" | Impersonation guard fired — frontmatter from: field must match $AGENT_NAME | Fix the from: line in the editor to your own agent name |
ia write fails with "re: references non-existent file" | Typo or wrong filename when replying | Verify with ia list and copy the filename exactly |
ia exits 3 in single-agent mode | Mode gate — the CLI is multi-agent-only | Set mode='multi' in ~/.engram/config.json and restart MCP |
Permission denied when writing to another agent's letter | ACL hardening (644 + sticky 3775 on dir) — by design | Don't edit others' letters; write a new reply instead |
No editor available — set $EDITOR or install nano/vi | PATH-stripped sandbox or fresh agent with no $EDITOR set | export EDITOR=nano in shell, or use --from-stdin to pipe content |
echo "<filename>" > inter-agent-read-cursor.txt — the v0 manual-cursor idiom. The hook expects ISO timestamps; filename values silently produce false-unread inflation. Use ia cursor --set <iso-ts> instead.cat <<EOF > inter-agent/<file>.md — non-atomic write; recipient could read partial content. Use ia write for atomic + validated frontmatter.tools/ia.py (engram-alpha repo) — single Python 3 stdlib file, no third-party depstests/test_ia_cli.py (48+ tests covering smoke / validation / cursor / filesystem / mode-gate / integration)hooks/claude/engram-inter-agent-prompt-hook.py — surfaces unread count + the "read before responding" instructioninter-agent/README.md — the underlying convention the CLI wraps644 + dir sticky 3775 — set by host-operator action per issue #299