📘Best Practice: Content Migration Onboarding

Use this packet during onboarding to understand how to approach content migration in Guru. It walks through the key decisions in order — how content should connect (source, migrate, or MCP), how to structure your collections, and how collections and sources come together through Knowledge Agents and Skills.

Download file here

1️⃣ Where Does Your Content Live?

The Big Decision

Before building anything in Guru, decide how each piece of content should connect. The three paths below are not interchangeable — choose the wrong one and you'll be restructuring later.

🛤️ The Three Paths

🔗 Connect as a Source
Content stays in its original system and powers AI Answers through indexing. Fast to set up, no auditing required.

📥 Migrate into Guru
Content becomes native Guru cards inside collections. Best for long-term ownership and direct management.

⚡ Connect via MCP
Live, permission-aware access — with the ability to take actions like sending messages or updating records.

✅ Decision Criteria

Use a Source when:

Fastest path to value, no content audit needed
Only need to power Answers, not native cards
Want selective, admin-chosen content indexed
Want content trainable in Agent Center

Migrate when:

Content should live as Guru cards in collections
Want directly searchable native knowledge
Consolidating or replacing an external KB
Need long-term ownership inside Guru

Use MCP when:

Need broad, per-user permission-based access
Need real-time data, not indexed content
Need to take actions in the external tool
Agent Center indexing is not the priority

⚠️
Slack Exception
Neither Slack as a source nor Slack MCP can read Slack file attachment contents. Upload files directly to Guru or store them in a connected source like Google Drive to make them accessible.

In one line each:

Source — Selective · indexed · read-only · trainable
Migrate — Move knowledge into Guru as native cards
MCP — Live · permission-aware · action-capable

2️⃣ Building Your Foundation

Collections Structure

Collections are the top-level containers for all Guru content. Getting the structure right before migrating saves significant rework — they're both an organizational layer and a permissions boundary.

🏗️ The Three-Layer Structure

📁 Collection → Top-level container. Maps to a team or function. The primary permissions boundary.
🗂️ Folder → Organizes subtopics inside a collection. Folders stay within their collection.
📄 Card → Individual unit of knowledge. Can belong to multiple folders in the same collection.

🎯 Core Principles

01 · Map to ownership
One collection per major team or function. Someone needs to own verification and governance.

02 · Treat it as a permissions boundary
Collections control who sees what. Structure access intentionally — restructuring later is disruptive.

03 · Name and describe explicitly
Names and descriptions should immediately communicate purpose to anyone in the workspace.

04 · Assign a clear owner
Every collection needs an owner responsible for content health and verification cadence.

🚧 Key Constraints

One collection — A card or folder can only live in one collection at a time. Plan the structure before migrating; moving content later is disruptive.

Multi-folder — A card can belong to multiple folders, but only within the same collection. Cross-collection reuse requires a shared collection.

🤝
When content spans multiple teams
→ Create a dedicated shared collection for common content
→ Turn a reusable folder into its own standalone collection
→ Use folder-level permissions to control access within a collection
→ Share collections across workspaces read-only

3️⃣ Layering Intelligence

Agents and Skills

Collections and external sources hold the content — Knowledge Agents and Skills define how users interact with it. These are distinct layers with distinct jobs.

🧠 The Three-Layer Model

1 · Content Sources — What the Agent Knows
Agents draw from two kinds of input: Guru collections (cards and folders your team owns and maintains) and external connected sources (indexed third-party tools, MCP connections, or file uploads).
Collections · Connected Sources · MCP · File Uploads

2 · Knowledge Agent — Experience Layer
Controls how a team searches, asks questions, and acts on that content. Defines which sources are in scope, who has access, AI behavior, and where the agent surfaces — Slack, browser extension, API.

3 · Skill — Workflow inside an Agent
Specialized modes of behavior for different request types within one agent — product Q&A, billing help, and troubleshooting can each be a separate skill without requiring separate agents.

🧭 Which Layer Do You Need?

Signal	Right Answer	Why
Different content set, owner, or permissions	New Collection	Content governance lives at the collection level
Different team, audience, or channel	New Agent	Agents control who gets what experience and where
Same agent, different task or use case	New Skill	Avoids agent sprawl; one agent handles multiple workflow.

4️⃣ Quick Reference

All three frameworks at a glance

Keep this handy during your first 30 days. Every key decision from the onboarding, condensed into one place.

📊 Source vs. Migrate vs. MCP

Method	Use when…	Not right when…
Source	Content powers Answers but stays in its original system. Fast time-to-value.	You need content as native Guru cards or directly searchable knowledge.
Migrate	Content should live as Guru cards long-term. Replacing an external KB.	Content changes frequently and re-syncing would be burdensome.
MCP	Need real-time, permission-aware access or actions in the source tool.	Agent Center indexing and Answer training are the priority.

📊 Collections Structure

Rule	What it means in practice
Collections = ownership + permissions	One per major team or function. Assign an owner before migrating content in.
One collection per card/folder	Plan the structure first. Moving content after migration is disruptive.
Cross-team content → shared collection	Don't duplicate across collections. One shared collection, access controlled by permissions.

📊 Collection vs. Agent vs. Skill

Layer	Job	Create a new one when…
Collection	Organizes and governs content	Different content set, owner, or permissions boundary
Agent	Controls search and answer experience	Different audience, source set, behavior, or channel
Skill	Specialized workflow inside one agent	Same agent, different task type (Q&A vs. troubleshooting)

🔀 Decision Flow

Should this become native Guru cards? → Yes → Migrate
Need to take actions in the source tool? → Yes → MCP
Just needs to power Answers in place? → Yes → Source
New team, function, or permissions boundary? → New Collection
Different audience, source set, or channel? → New Agent
Same agent, different task type? → New Skill