/add-knowledge

user-invocable: false
description: Add a knowledge source (public website or SharePoint) to a Copilot Studio agent. Use when the user asks to add a knowledge source, documentation URL, website, or SharePoint site for the agent to search.
argument-hint: <url>
allowed-tools: Bash(node *schema-lookup.bundle.js *), Read, Write, Glob
context: fork
agent: copilot-studio-author

Add Knowledge Source

Add a knowledge source to the agent. Supports **Public Website**, **SharePoint**, and **Custom API** sources.

Instructions

1. **Auto-discover the agent directory**:

   Glob: **/agent.mcs.yml

NEVER hardcode an agent name.

2. **Parse the arguments** to extract:

• URL
• Name / description (optional)

3. **Determine the source type** from the user's request:

• If the URL contains `sharepoint.com` → use `SharePointSearchSource` (but first normalize the URL — see below)
• If the user wants to connect a **custom search API or database** → use `OnKnowledgeRequested` (see Custom API section below)
• Otherwise → use `PublicSiteSearchSource`

4. **If SharePoint: normalize the URL** before using it. Copilot Studio requires a direct folder path like: `https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder`

Users often paste URLs in other formats. Handle them as follows:

| URL pattern | Example | Action | |---|---|---| | **Direct path** (`/sites/.../Shared%20Documents/...`) | `https://x.sharepoint.com/sites/Site/Shared%20Documents/Folder` | **Use as-is** — this is the correct format | | **AllItems.aspx with `?id=` param** (`...AllItems.aspx?id=...`) | `https://x.sharepoint.com/.../AllItems.aspx?id=%2Fsites%2FSite%2FShared%20Documents%2FFolder&viewid=...` | **Extract and decode** the `id` query parameter. URL-decode it to get the path (e.g. `/sites/Site/Shared%20Documents/Folder`), then prepend the origin (`https://x.sharepoint.com`) to build the direct path. Drop all query parameters (`?id=`, `&viewid=`, etc.) | | **Sharing link** (`/:f:/s/...` or `/:x:/s/...`) | `https://x.sharepoint.com/:f:/s/Site/EncodedToken?e=abc` | **Cannot convert** — these are opaque sharing tokens with no extractable folder path. Ask the user: *"That's a SharePoint sharing link — I can't extract the folder path from it. Could you navigate to the folder in SharePoint, copy the URL from the browser address bar, and paste it here?"* |

**Encoding rule:** Spaces in the final URL must be encoded as `%20` (e.g. `Shared%20Documents`, not `Shared Documents`).

5. **Look up the knowledge source schema**:

   node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve KnowledgeSourceConfiguration

6. **Generate the knowledge source YAML**.

**Public Website:**

> `PublicSiteSearchSource` uses Bing search to find relevant snippets within the scoped URL. It does **not** crawl or summarize full pages. The URL defines a search scope (not a specific page), and supports a **maximum depth of 2 levels** beyond the domain (e.g. `https://example.com/docs/api` works, `https://example.com/docs/api/v2` is too deep and will be ignored).

   # Name: <Name>
   # <Description of what this knowledge source provides>
   kind: KnowledgeSourceConfiguration
   source:
     kind: PublicSiteSearchSource
     site: https://www.example.com/docs

**SharePoint:**

   # Name: <Name>
   # <Description of what this knowledge source provides>
   kind: KnowledgeSourceConfiguration
   source:
     kind: SharePointSearchSource
     site: https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder

7. **Always include `# Name:` and a description comment** at the top. These are important for identifying the knowledge source.

8. **Save** to the agent's `knowledge/<descriptive-name>.knowledge.mcs.yml` directory

Custom API via OnKnowledgeRequested (YAML-only)

When the user wants to connect a **proprietary search API or database** not natively supported by Copilot Studio, use the `OnKnowledgeRequested` trigger. This is a **YAML-only capability with no UI designer** — it intercepts knowledge search requests and lets you call a custom API to populate results.

**How it works:** 1. Create a topic with `OnKnowledgeRequested` trigger 2. Use `System.SearchQuery` (the AI-rewritten query) as input to your API call 3. Transform API results into the required schema: `Content`, `ContentLocation`, `Title` 4. Set `System.SearchResults` with the transformed results

**Use the template:** `${CLAUDE_SKILL_DIR}/../../templates/topics/custom-knowledge-source.topic.mcs.yml`

**Prerequisites:** The user needs a connector action (in `actions/`) that calls their search API. If they don't have one yet, they should create it through the Copilot Studio UI or VS Code extension first.

Dynamic Knowledge URLs with Global Variables

Knowledge source URLs support `{VariableName}` placeholders — typically global variables — for dynamic routing based on user context. This is powerful for scenarios where different users need different knowledge sources (e.g., geolocation-specific SharePoint folders, region-specific documentation).

**Pattern**: Define a global variable (via `/copilot-studio:add-global-variable`), populate it early in the conversation (e.g., in an OnActivity/conversation-init topic based on user profile or geolocation), then reference it in the knowledge source URL with Power Fx string interpolation.

**SharePoint example** — a workforce agent that routes to different SharePoint folders per region:

# Name: Regional HR KB
# This knowledge source provides HR information from the {Global.UserKBURL} SharePoint.
kind: KnowledgeSourceConfiguration
source:
  kind: SharePointSearchSource
  site: =$"{Global.UserKBURL}"

**Public website example** — documentation site with region-specific subpaths:

# Name: Regional Docs
# Documentation for the user's region at {Global.Region}.
kind: KnowledgeSourceConfiguration
s