Agent Report YAML Protocol for Agent Inbox

Agent Inbox turns Markdown files into a readable inbox for AI agent work. Each report file can carry a small YAML frontmatter envelope so the app can identify source, status, priority, and timestamps.

The protocol is intentionally local-first. Markdown files stay in folders you control, and Agent Inbox indexes them after you authorize the folder on iOS or macOS.

Folder Layout

Connect a folder in the app, then let agents write Markdown reports inside it:

Reports Folder/
  reports/
    daily-gsc.md

Agent Inbox scans explicitly connected folders. It skips heavy development directories such as .git, node_modules, .build, and DerivedData.

Agent Report Frontmatter

Each AI-generated report is a Markdown file with a small frontmatter envelope. Put the actual report in the Markdown body.

---
report_version: 1
type: agent_report
title: Daily GSC SEO Report
source: openclaw
agent: clawceo
status: needs_review
priority: normal
created_at: 2026-05-15T09:04:32+08:00
---

# Daily GSC SEO Report

## TL;DR

Organic clicks increased slightly, but CTR dropped on two high-impression pages.

## Recommended Action

Generate new title and meta variants for the affected pages.

Report Fields

Field	Required	Description
`report_version`	No	Report envelope version. Use `1`.
`type`	Recommended	Use `agent_report` for agent output. `manual_note` is also supported.
`title`	No	Display title. If omitted, Agent Inbox falls back to the first `#` heading or filename.
`source`	No	Origin such as `codex`, `openclaw`, `github_actions`, `cron`, or `mac_helper`.
`agent`	No	Agent name or role.
`status`	No	One of `done`, `needs_review`, `failed`, `blocked`, `partial`, or `draft`.
`priority`	No	Free-form priority such as `low`, `normal`, `high`, or `urgent`.
`created_at`	No	ISO 8601 timestamp, with or without fractional seconds.

Agent Inbox treats a Markdown file as an agent report candidate only when frontmatter has a supported type.

Agent Prompt Template

Give this to an AI agent that writes reports:

Write a complete Markdown report for Agent Inbox.

Use YAML frontmatter:
- report_version: 1
- type: agent_report
- title: <clear report title>
- source: <agent or automation source>
- agent: <agent name>
- status: needs_review, done, failed, blocked, partial, or draft
- priority: low, normal, high, or urgent
- created_at: <ISO 8601 timestamp>

Keep business metrics and raw provider data in the Markdown body, not in frontmatter.
Do not include API keys, tokens, cookies, or private credentials.

Compatibility Notes

The current app indexes local Markdown files only after folder authorization. The same folder may need to be connected separately on iPhone and Mac because Apple security-scoped file access is device-local.