Agent Factory: Email triage SKILL.md — reference specification for v1 validation

[kovtcharov-amd]

Context

The Agent Factory v1 uses email triage as the proving ground. This issue covers writing the reference SKILL.md specification that the factory consumes to produce the email triage agent.

Scope

• Write skills/email-triage/SKILL.md with:
  • Full YAML frontmatter: name, version, description, category, tags, model requirements, capabilities, permissions, connectors
  • Capabilities: categorize_emails, summarize_inbox, draft_responses, manage_calendar, organize_folders
  • Permissions: network:read:imap,smtp; network:write:smtp
  • Connectors: Gmail (OAuth2), Outlook (OAuth2)
  • Eval config: personas (executive, developer, manager), scenarios (morning_triage, urgent_detection, meeting_negotiation, spam_filtering, thread_context)
  • Detailed markdown body describing expected agent behavior, edge cases, and quality expectations
• Create eval scenario YAML files for each scenario listed in the spec
• Create synthetic email dataset for the eval sandbox (50+ emails across personas, threads, spam, attachments)
• Validate: factory can parse the SKILL.md and scaffold an agent from it

Acceptance Criteria

• SKILL.md passes factory parser validation
• All 5 capabilities are clearly specified with expected behaviors
• Eval scenarios cover happy path + adversarial cases
• Synthetic email dataset is realistic (multiple personas, threads, spam)
• Factory scaffold produces working agent from this spec

Ref: docs/plans/agent-factory.mdx "Reference: Email Triage SKILL.md"

[github-actions]

Scope is clear and the sister issues (#1109, #1111, #1113, #1116, #1118, #1119, #1120, #1122) frame this nicely as the reference spec the factory chews on. Before someone picks this up, a few things worth resolving so the SKILL.md produced here doesn't get rewritten as soon as the parser in #1111 lands:

🟡 Missing parent plan. Every Agent Factory issue refs docs/plans/agent-factory.mdx, but that file doesn't exist in the repo yet — only docs/plans/skill-format.mdx and docs/plans/email-triage-agent.mdx. Either land the factory plan first, or this issue should explicitly say "draft agent-factory.mdx alongside the SKILL.md." Without it, the "Reference: Email Triage SKILL.md" anchor is dangling and the scaffolder in #1111 has no source of truth for its prompt.

🟡 Schema drift vs. skill-format.mdx v0.1.0. The fields requested here (category, capabilities, connectors, eval config with personas/scenarios) aren't in the current SKILL.md schema (docs/plans/skill-format.mdx §2.1 — only permissions, requirements, tools, security_tier, etc.). These are useful factory-time additions, but they should be reconciled with the skill-format spec (either extending it or namespacing under a factory: block) — otherwise the marketplace parser and the factory parser will diverge from day one. Permission syntax in the issue (network:read:imap,smtp; network:write:smtp) also doesn't match §3.2's scoping format — worth picking one.

🟢 Source material exists. docs/plans/email-triage-agent.mdx already has the C1/C2 behavioral spec, cohort taxonomy, urgency scoring, and edge cases — the SKILL.md body should reference / extract from it rather than re-derive. The synthetic dataset can lean on the persona definitions (executive / developer / manager / etc.) already discussed in §16–17.

🟢 Skill location. skill-format.mdx §5.1 puts installed skills at ~/.gaia/skills/<name>/. For an in-tree reference spec consumed by the factory, a top-level skills/email-triage/ (as the issue says) is sensible — but worth confirming with @kovtcharov-amd whether the repo gets a skills/ directory or these live under src/gaia/factory/skills/.

@kovtcharov-amd — can you confirm (1) whether docs/plans/agent-factory.mdx should be drafted as part of this issue or a separate prerequisite, and (2) whether the SKILL.md schema extensions (capabilities/connectors/eval) belong in skill-format.mdx or in a factory-specific overlay?