agent-output-formats

Agent Output Formats

When to use this skill

Activate when:

• A consumer has run a SfSkills runtime agent and needs the result in a format beyond the canonical markdown+JSON (e.g. Excel for a security review meeting, PDF for a compliance audit, Notion card for a team wiki, ServiceNow ticket for tracking remediation).
• A request comes in to "export the agent's output as X" where X is not markdown or JSON.
• You want to avoid the pattern where the consuming AI regenerates the report from scratch in the new format, OR installs new libraries into the user's project.

Do NOT use this skill for:

• Authoring a new agent's primary output format (use agents/_shared/DELIVERABLE_CONTRACT.md).
• Designing a new agent's native output shape (use agents/_shared/schemas/output-envelope.schema.json).
• Large-scale data exports from Salesforce orgs (use skills/data/bulk-api-2-patterns).

Core principle — convert, don't regenerate

Every runtime agent produces a canonical pair: markdown + JSON envelope. That pair IS the source of truth. When a consumer asks for Excel/PDF/etc., the correct answer is to convert from that pair, not to re-run the agent with different instructions.

Reasons:

1. Reproducibility — the canonical deliverable is checked into docs/reports/. Six months later, anyone can regenerate the Excel from it. If the consuming AI regenerates by re-asking the agent, the output may differ due to LLM stochasticity.
2. Auditability — the run_id in the envelope is the tracking key. The Excel/PDF should reference it in its header, so "which run produced this?" is always answerable.
3. Minimal dependencies — reinstalling exceljs, xlsxwriter, weasyprint, etc. into a consumer's project every time someone wants a different format bloats their project's dependency tree.

Conversion decision tree

START: Consumer wants deliverable in format X.

Q1. Is X markdown or JSON?
    → Already the canonical form. No conversion needed; hand them the file path.

Q2. Is X a format the consumer's existing tooling handles natively?
    ├── Slack message / email body → paste the TL;DR + envelope-link from the markdown
    ├── Confluence / Notion / Obsidian → import the markdown directly (all support markdown import)
    ├── Jira / ServiceNow ticket → paste TL;DR in description + link the report file
    └── GitHub issue → embed markdown inline; link the report path
    → Prefer this path. Zero new dependencies.

Q3. Does the consumer want a "table" from the markdown?
    ├── CSV: extract markdown tables using `pandoc` (most dev machines have it)
    ├── Excel from the JSON envelope: use `jq` + `csv2xlsx` CLI tools (lighter than a full SDK)
    └── If neither pandoc nor jq: recommend installing pandoc (1 tool, system-level, widely used)

Q4. Does the consumer want PDF?
    → `pandoc <report>.md -o <report>.pdf` — single command, no new project deps
    → If pandoc isn't available: recommend a system-wide install, NOT a project-level dep

Q5. Does the consumer want something format-specific (e.g. ServiceNow change ticket)?
    → Extract the fields from the JSON envelope (it's keyed for exactly this)
    → Template into the target system via its normal integration path
    → Do NOT ask the agent to regenerate in the target format