Virlo for Vellum

The official Virlo plugin for Vellum assistants. Gives your always-on personal AI real-time short-form social intelligence: ask "what's going viral in my niche right now, and why?" and get back Virlo's weighted virality score, rising-creator outliers, winning content formats, and AI trend analysis across TikTok, YouTube Shorts, and Instagram Reels.

Quick start

# 1. Hatch a Vellum assistant
vellum hatch --name my-assistant --remote docker -d

# 2. Store your Virlo API key (get one at https://dev.virlo.ai/dashboard)
vellum exec my-assistant -- assistant credentials set "virlo_tkn_<your_key>" \
  --service virlo --field api_key

# 3. Install the Virlo plugin (triggers the init hook)
vellum exec my-assistant -- assistant plugins install \
  https://github.com/Virlo-AI/virlo-integrations/tree/main/integrations/vellum --name virlo

# 4. Start a conversation
vellum message my-assistant "what's going viral in fitness on TikTok right now?"

The assistant will resolve the API key from the credential store at runtime, kick off a Content Research Agent (~15-20 min), and surface results when ready. It never blocks you synchronously.

What it does

Built on Virlo's forward-facing surfaces:

• Content Research Agents (/v1/agents) - the unified research engine. One resource, two modes:
  • one-shot (is_recurring: false) - niche search: "what's viral in London TikTok fitness right now?"
  • recurring (is_recurring: true) - monitoring: "keep watching this niche and tell me weekly."
• Satellite - creator, sound & video deep-dives: "tell me about this creator / why did this video pop?"
• Trends - regional (global/us/gb/au), momentum-ranked trend detection, including a free emerging feed for "what's about to take off."

Plugin structure

integrations/vellum/
  package.json              Plugin manifest (name, version, peerDependencies)
  mcp.json                  MCP server connection config (for future MCP support)
  hooks/
    init.ts                 Logs plugin registration (no config/env state)
    shutdown.ts             No-op (no state to clean up)
  skills/
    virlo/
      SKILL.md              The assistant skill: how to use Virlo's API
      scripts/              Runnable TypeScript scripts for each flow
        virlo-client.ts     Shared helper (credential resolution, fetch, polling)
        whats-viral.ts      One-shot niche search flow
        recurring-monitor.ts  Recurring monitor creation
        creator-deep-dive.ts  Satellite creator lookup + video outlier
      references/           Worked flow documentation + golden prompts
        agent-playbook.md   How to interpret results (weighted score, formats)
        golden-prompts.md   Acceptance criteria for QA
        whats-viral-in-my-niche.md
        recurring-niche-monitor.md
        creator-deep-dive.md