add-knowledge

Name: add-knowledge
Author: microsoft

372stars76forks

How to install add-knowledge?

microsoft/skills-for-copilot-studio/add-knowledge

$npx -y skills add microsoft/skills-for-copilot-studio --skill add-knowledge

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Add Knowledge Source
2
3	Add a knowledge source to the agent. Supports Public Website, SharePoint, and Custom API sources.
4
5	## Instructions
6
7	1. Auto-discover the agent directory:
8	```
9	Glob: **/agent.mcs.yml
10	```
11	NEVER hardcode an agent name.
12
13	2. Parse the arguments to extract:
14	- URL
15	- Name / description (optional)
16
17	3. Determine the source type from the user's request:
18	- If the URL contains `sharepoint.com` → use `SharePointSearchSource` (but first normalize the URL — see below)
19	- If the user wants to connect a custom search API or database → use `OnKnowledgeRequested` (see Custom API section below)
20	- Otherwise → use `PublicSiteSearchSource`
21
22	4. If SharePoint: normalize the URL before using it. Copilot Studio requires a direct folder path like:
23	`https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder`
24
25	Users often paste URLs in other formats. Handle them as follows:
26
27	\| URL pattern \| Example \| Action \|
28	\|---\|---\|---\|
29	\| Direct path (`/sites/.../Shared%20Documents/...`) \| `https://x.sharepoint.com/sites/Site/Shared%20Documents/Folder` \| Use as-is — this is the correct format \|
30	\| 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.) \|
31	\| 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?" \|
32
33	Encoding rule: Spaces in the final URL must be encoded as `%20` (e.g. `Shared%20Documents`, not `Shared Documents`).
34
35	5. Look up the knowledge source schema:
36	```bash
37	node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve KnowledgeSourceConfiguration
38	```
39
40	6. Generate the knowledge source YAML.
41
42	Public Website:
43
44	> `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).
45
46	```yaml
47	# Name: <Name>
48	# <Description of what this knowledge source provides>
49	kind: KnowledgeSourceConfiguration
50	source:
51	kind: PublicSiteSearchSource
52	site: https://www.example.com/docs
53	```
54
55	SharePoint:
56	```yaml
57	# Name: <Name>
58	# <Description of what this knowledge source provides>
59	kind: KnowledgeSourceConfiguration
60	source:
61	kind: SharePointSearchSource
62	site: https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder
63	```
64
65	7. Always include `# Name:` and a description comment at the top. These are important for identifying the knowledge source.
66
67	8. Save to the agent's `knowledge/<descriptive-name>.knowledge.mcs.yml` directory
68
69	## Custom API via OnKnowledgeRequested (YAML-only)
70
71	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.
72
73	How it works:
74	1. Create a topic with `OnKnowledgeRequested` trigger
75	2. Use `System.SearchQuery` (the AI-rewritten query) as input to your API call
76	3. Transform API results into the required schema: `Content`, `ContentLocation`, `Title`
77	4. Set `System.SearchResults` with the transformed results
78
79	Use the template: `${CLAUDE_SKILL_DIR}/../../templates/topics/custom-knowledge-source.topic.mcs.yml`
80
81	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.
82
83	## Dynamic Knowledge URLs with Global Variables
84
85	Knowledge source URLs support `{VariableName}` placeholders — typically global variables — for dynamic routing based on use

People who liked this also viewed

6 picks

Type

add-knowledge

372stars76forks

View on GitHub

How to install add-knowledge?

microsoft/skills-for-copilot-studio/add-knowledge

$npx -y skills add microsoft/skills-for-copilot-studio --skill add-knowledge

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Add Knowledge Source
2
3	Add a knowledge source to the agent. Supports Public Website, SharePoint, and Custom API sources.
4
5	## Instructions
6
7	1. Auto-discover the agent directory:
8	```
9	Glob: **/agent.mcs.yml
10	```
11	NEVER hardcode an agent name.
12
13	2. Parse the arguments to extract:
14	- URL
15	- Name / description (optional)
16
17	3. Determine the source type from the user's request:
18	- If the URL contains `sharepoint.com` → use `SharePointSearchSource` (but first normalize the URL — see below)
19	- If the user wants to connect a custom search API or database → use `OnKnowledgeRequested` (see Custom API section below)
20	- Otherwise → use `PublicSiteSearchSource`
21
22	4. If SharePoint: normalize the URL before using it. Copilot Studio requires a direct folder path like:
23	`https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder`
24
25	Users often paste URLs in other formats. Handle them as follows:
26
27	\| URL pattern \| Example \| Action \|
28	\|---\|---\|---\|
29	\| Direct path (`/sites/.../Shared%20Documents/...`) \| `https://x.sharepoint.com/sites/Site/Shared%20Documents/Folder` \| Use as-is — this is the correct format \|
30	\| 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.) \|
31	\| 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?" \|
32
33	Encoding rule: Spaces in the final URL must be encoded as `%20` (e.g. `Shared%20Documents`, not `Shared Documents`).
34
35	5. Look up the knowledge source schema:
36	```bash
37	node ${CLAUDE_SKILL_DIR}/../../scripts/schema-lookup.bundle.js resolve KnowledgeSourceConfiguration
38	```
39
40	6. Generate the knowledge source YAML.
41
42	Public Website:
43
44	> `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).
45
46	```yaml
47	# Name: <Name>
48	# <Description of what this knowledge source provides>
49	kind: KnowledgeSourceConfiguration
50	source:
51	kind: PublicSiteSearchSource
52	site: https://www.example.com/docs
53	```
54
55	SharePoint:
56	```yaml
57	# Name: <Name>
58	# <Description of what this knowledge source provides>
59	kind: KnowledgeSourceConfiguration
60	source:
61	kind: SharePointSearchSource
62	site: https://contoso.sharepoint.com/sites/MySite/Shared%20Documents/MyFolder
63	```
64
65	7. Always include `# Name:` and a description comment at the top. These are important for identifying the knowledge source.
66
67	8. Save to the agent's `knowledge/<descriptive-name>.knowledge.mcs.yml` directory
68
69	## Custom API via OnKnowledgeRequested (YAML-only)
70
71	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.
72
73	How it works:
74	1. Create a topic with `OnKnowledgeRequested` trigger
75	2. Use `System.SearchQuery` (the AI-rewritten query) as input to your API call
76	3. Transform API results into the required schema: `Content`, `ContentLocation`, `Title`
77	4. Set `System.SearchResults` with the transformed results
78
79	Use the template: `${CLAUDE_SKILL_DIR}/../../templates/topics/custom-knowledge-source.topic.mcs.yml`
80
81	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.
82
83	## Dynamic Knowledge URLs with Global Variables
84
85	Knowledge source URLs support `{VariableName}` placeholders — typically global variables — for dynamic routing based on use

People who liked this also viewed

6 picks

Type