agent-hq

A Vellum assistant plugin that turns a Notion page into your team's Agent HQ: a shared hub where teammates publish the skills their assistants have learned, and every assistant on the team picks them up.

• I want to leverage my teammates' expertise without bothering them directly.
• I want my assistant to get better passively.
• I don't want to spend tokens recreating skill procedures a teammate already made.

How it works

Notion "Agent HQ" page
  └── "Shared Skills" database            one row per shared skill
        ▲              │
        │  publish     │  sync
        │              ▼
  your local skills    plugin cache + materialized hq-* skills
                                │
                                ▼
                       system-prompt digest

1. Connect. The plugin uses your existing Notion connection (managed OAuth by default; the token never leaves the platform). If Notion isn't connected yet, the agent-hq skill walks you through connecting it in chat.
2. Bootstrap. The first teammate creates the hub: an "Agent HQ" page with a "Shared Skills" database, placed under any Notion page they choose and shared with the team. Everyone else just shares that page with their own Vellum integration.
3. Sync. sync pulls the database, caches it in the plugin's data/ directory, and materializes each teammate skill as a normal catalog skill named hq-<id>. Your assistant can load them like any other skill.
4. Publish. Local procedure skills (including ones your assistant distilled from its own work) can be published to the hub, after an explicit in-chat confirmation. Publishing is instruction-only: SKILL.md and references/*.md travel; scripts and other executables never do.
5. Stay aware. A tiny pre-model-call hook injects a compact digest (hub status, teammate skills, unpublished local procedures) into the main agent's context, so the assistant knows what the team shares without being asked. Set inject: false in config.json to turn that off.

All Notion traffic happens through assistant oauth request when the assistant runs the skill's scripts. Hooks never touch the network: they only read the local cache, so boot and per-turn overhead stay negligible and every failure degrades to "no digest".

Install

assistant plugins install vellum-ai/agent-hq

Then ask your assistant to "set up Agent HQ". It loads the agent-hq skill and takes it from there.

Configuration (config.json)

Key	Default	Meaning
hqTitle	"Agent HQ"	Title of the hub page searched for in Notion
inject	true	Inject the digest into main-agent context
staleAfterHours	24	Cache age after which the digest suggests a sync
digestMaxChars	1500	Hard cap on the injected digest

Security notes

• Skills synced from the hub are teammate-authored instructions. They are sanitized on sync (inline command expansions are neutralized) and no executable files are synced, but treat hub content with the same trust you give a teammate's Notion page: the assistant reads it as guidance.
• Publishing writes to a shared team surface, so every publish is gated on an explicit in-chat confirmation.
• The plugin never sees or stores your Notion token. Managed OAuth requests are brokered by the Vellum platform.

Development

bun install
bunx tsc --noEmit
bun test

DESIGN.md documents the architecture and the contracts between hooks, cache, and skill scripts. Local iteration: copy the repo into $VELLUM_WORKSPACE_DIR/plugins/agent-hq and check assistant plugins list reports status ok.

License

MIT