martin-hausleitner/martins-awesome-skills/ai-research-output-publisher

AI Research Output Publisher

Use this skill after a Deep Research, Agent, or long AI workflow has finished and you need a polished result message plus optional Notion sync.

It does not run the browser workflow itself. It consumes a result JSON file from ai-research-browser, Oracle harvest output, or another orchestrator and produces:

• a clear chat message with icon, readable links, and copy-ready summary text;
• support for multiple research results in one notification;
• average research duration and total duration metrics;
• a Notion page payload where the summary appears above the full text;
• optional live Notion page creation only when explicitly allowed.
• optional live chat/webhook delivery only when explicitly allowed.

Safe Default

Render a message and Notion payload without external writes:

python3 skills/productivity/ai-research-output-publisher/scripts/ai_research_output_publisher.py render \
  --input /tmp/research-results.json \
  --message-output /tmp/research-message.md \
  --payload-output /tmp/research-notion-payload.json

The chat message includes summary text by default. Add --chat-summary off when only links and metrics should be shown. Secret-like values are redacted by default (--privacy redacted), including emails, obvious API tokens, bearer headers, proxy credentials, and URL query strings. Use --privacy full only for private/local artifacts that must preserve exact text.

Try the bundled public-safe example:

python3 skills/productivity/ai-research-output-publisher/scripts/ai_research_output_publisher.py render \
  --input skills/productivity/ai-research-output-publisher/examples/research-results.example.json

Expected message shape: examples/research-message.example.md.

Input Shape

{
  "job_id": "research-batch-001",
  "title": "Weekly AI research",
  "results": [
    {
      "title": "Obsidian AI plugins",
      "provider": "gemini",
      "mode": "deep-research",
      "status": "completed",
      "deep_research_url": "https://example.com/research",
      "pspin_url": "https://example.com/pin",
      "summary": "Short summary shown in chat and at the top of Notion.",
      "text": "Full research report.",
      "research_duration_seconds": 720,
      "total_duration_seconds": 900
    }
  ]
}

The script accepts research_url, deep_research_url, chat_url, or source_url for the main research link.

Publish To Notion

Live Notion writes require explicit opt-in:

NOTION_API_KEY="secret-token" \
python3 skills/productivity/ai-research-output-publisher/scripts/ai_research_output_publisher.py publish-notion \
  --input /tmp/research-results.json \
  --parent-page-id "<notion-parent-page-id>" \
  --allow-external-write

Without --allow-external-write, the command writes only the planned Notion payload. Live writes still use redacted mode by default; pass --privacy full only when the destination workspace is allowed to receive the exact captured text.

Send Chat Notification

Prepare a chat/webhook notification without sending:

python3 skills/productivity/ai-research-output-publisher/scripts/ai_research_output_publisher.py send-chat \
  --input /tmp/research-results.json \
  --channel webhook \
  --webhook-url "https://example.invalid/research-webhook"

Live delivery requires explicit opt-in:

python3 skills/productivity/ai-research-output-publisher/scripts/ai_research_output_publisher.py send-chat \
  --input /tmp/research-results.json \
  --channel discord \
  --webhook-url "<discord-webhook-url>" \
  --allow-external-write

Supported channels are webhook, discord, and telegram. Tokens and destinations must come from local environment variables or CLI arguments and must never be committed.

Output Contract

Each notification includes:

• an icon-based headline;
• one row per completed result;
• readable Markdown links for Deep Research and PSPin;
• average research duration and average total duration;
• copy-ready summary text;
• button metadata for copy, Deep Research, PSPin, and Notion page actions.
• optional chat_delivery status when sent through the gated send-chat command.

Verification

Run the deterministic local E2E test:

python3 -m unittest discover -s skills/productivity/ai-research-output-publisher/tests -p 'test_*.py'

The tests use fake input and a local fake Notion endpoint. They do not write to a real workspace.