AGENTIC AI: APPLYING SHAREPOINT.MD
- Jul 22
- 10 min read
Author: Jonathan Stuckey
Audience: Solution designer, IT Operations, Information Advisor
Reading: medium-long read, guidance
If you deployed agents in SharePoint Online and noticed that responses vary in quality between sites, or that users get sensible but entirely generic answers to questions that deserve site-specific response, then SHAREPOINT.md is the one for you. Deploying SharePoint.md offers a practical way to extend to Copilot Agents in SharePoint, with intelligent, task-focused automation.
SHAREPOINT.MD - a site context file
SHAREPOINT.md changes how AI understands your SharePoint
All agent assets now have a managed home in the shape of 'Agent Assets' library, which is created when you activate the AI Agent feature on a site. With this feature update comes a capability which is easy to overlook but may have the most useful impact on the quality of AI responses across your site(s): the SHAREPOINT.md file.
What is it?
In plain terms SHAREPOINT.md is just a Markdown file placed at the root of a site's Agent Assets library. The path is always:
/{site_name}/Agent Assets/SHAREPOINT.mdWhen a user opens Copilot in SharePoint on that site, the file loads automatically into the conversation as background context - before the user types anything. Every prompt that follows is interpreted with the site's institutional knowledge already in scope.
The user does not attach it or reference it. The site owner writes it once; every subsequent chat on that site benefits from it.
Think of it as the standing brief you give a new colleague before they start answering questions on your behalf. Without the brief, they give plausible answers based on general SharePoint knowledge. With it, they give correct answers based on how this particular site actually operates.
The capability sits within what Microsoft calls the “What to Know” component of AI in SharePoint and AI-assisted content generation, which are distinct from Skills (How to Act) or Design (How it looks). All three are complementary, but SHAREPOINT.md is the foundation.
SHAREPOINT.md and Skills
What's the Difference?
SHAREPOINT.md is passive context. It loads in the background of every Copilot chat on the site and shapes how the AI interprets the site, its content, and its processes. It does not trigger actions.
Skills are active and invocable. They define a repeatable multi-step process, stored as a Markdown file in {site_name}/AgentAssets/Skills/<name>/SKILL.md which the AI executes on demand. Skills cannot execute well without accurate context. SHAREPOINT.md is what provides it.
The practical rule: if it's what the AI needs to know, it belongs in SHAREPOINT.md. If it's what the AI needs to do, it belongs in a Skill.
What goes inside it
A well-structured SHAREPOINT.md typically covers the following:
Section | What the AI uses it for |
Site identity & overview | Understand the site's purpose; scope every response accordingly |
Document libraries | Know which library to reference and what the key columns mean |
Lists | Understand where reference data lives and how it feeds into processes |
Key pages | Direct users to the right page for specific tasks |
Workflows & processes | Walk users through exact steps; flag which transitions are manual |
Terminology & glossary | Interpret site-specific terms, acronyms, and column values correctly |
Rules for AI | Encode hard rules on what to say, and what to never imply |
Contacts & ownership | Point users to the right person when the AI should not answer directly |
The Rules for AI section deserve particular attention. This is where you encode the non-obvious guardrails that a generic AI would get wrong e.g. which actions must always be performed by a human, which documents must never be created by uploading, and what terminology has a specific meaning in your organisation's context.
Key to remember when creating a SHAREPOINT.md file:
Write the file from the AI's perspective, not a human reader's,
Use tables, labelled sections, and short paragraphs over long prose, and
Keep it between approximately 3,000 - 4,000 words
Use these rules-of-thumb so it will load fully, and consistently, on every chat.
Activating the file
Two steps are required before the file has any effect:
Activate the Agent Assets site collection feature. Go to Site Settings → Site collection features → Agent Assets → Activate. This creates the library.
Upload the file. Place SHAREPOINT.md at the root of the Agent Assets library.
NOTE: uppercase the filename, the automatic discovery mechanism depends on exact casing
The file can also be created or updated via a Copilot chat on the site using the set_context_file command (see Resources). For complex process-heavy sites, authoring the file manually gives better control. For simpler sites or incremental updates, the conversational approach is faster.
Example: HR Personnel Files Site
In real sites and use-cases we want to see the actual impact of using this additional layer for the generative AI and Agent.
Consider a People & Culture team managing employment documentation on an HR Personnel Files SharePoint site. The site has:
three main libraries - Employment Contracts, Performance Reviews, and Policy Acknowledgements,
an Employees list used as the primary employee register,
the site uses Content Assembly with a governed document Template for employee file, and
an Automate workflow is linked to the library for capturing signatures.
Without a SHAREPOINT.md context file, the site is just a SharePoint site. Copilot knows what SharePoint is; it does not know how this site works.
Before and After
To show what the impact is the example below shows same prompt, but with two different outcomes:
Prompt from an HR Coordinator | "How do I create a new employment contract for a permanent staff member?" |
Before we apply .md guardrails:
❌ Without SHAREPOINT.md | RESPONSE: "You can create a new employment contract by clicking New in your Documents library and selecting the relevant document type. If a template exists in the site, it will appear in the template picker. Alternatively, you can upload a completed contract from your local device." |
The answer is technically correct for SharePoint in general, but entirely wrong for this site. In this case uploading an unformatted document breaks the site's version control and signature workflow.
✅ With SHAREPOINT.md | RESPONSE: "Employment contracts on this site are created using Content Assembly — do not upload a contract directly to the library. To get started, open the Employment Contracts library, click New → Create from template, and select the Standard Employment Agreement or Fixed-Term Agreement template depending on the contract type. You will be prompted to complete the employee reference (format: EMP-XXXX), start date, and direct manager before the document is generated. Once generated, the contract moves to Draft status. The next step — sending for e-signature — must be completed manually by the HR Manager. The AI cannot initiate the signature workflow." |
The difference is not subtle. The second response would be impossible without the context file encoding: the Content Assembly requirement, the template names, the employee reference format, and the explicit guardrail on the signature step.
A few lines in the SHAREPOINT.md Rules section, such as:
Employment contracts must always be created via Content Assembly. Never advise uploading a document to the Employment Contracts library. The e-signature step is a manual human action and cannot be initiated by AI....will produce the second response instead of the first.
Current constraints, limitations, and gaps
SHAREPOINT.md, and SharePoint Skills, are both part of the recently GA'd release, but this is still early-days and there are a number of limitations to manage before scaling adoption across your tenant:
A Microsoft 365 Copilot licence is required. The AI in SharePoint grounding capability, including SHAREPOINT.md loading, is tied to the Copilot licence. Users without a Copilot license cannot benefit, regardless of how well the context file is written.
File scope is site-level only. There is no hub-level or tenant-level context file today. Organisation-wide terminology, standard acronyms, and shared governance rules must be replicated across every site's SHAREPOINT.md independently. This is the most significant structural gap …and the most likely candidate for a future platform improvement.
File size affects load reliability. Files above approximately 4,000 words may load slowly or partially. This forces prioritisation: the context file should contain only what materially affects AI behaviour, not a full site guide.
Table parsing can be inconsistent. Microsoft acknowledges that Copilot may not reliably parse complex table structures in SharePoint content. Use tables for glossaries and structured reference data but keep critical process logic in clearly labelled prose sections.
Content freshness is the owner's responsibility. The file does not update itself. When processes change, libraries are renamed, or new lists are added, the context file must be updated manually or via the set_context_file command. A stale context file produces confidently wrong responses.
The file is not a substitute for Skills. Multi-step, repeatable process instructions belong in Skills, not in SHAREPOINT.md. The context file prepares the AI to understand the site; Skills direct the AI to act on it.
Standard Markdown files in SharePoint libraries behave differently. SHAREPOINT.md works because it loads via the Agent Assets discovery mechanism, not via standard SharePoint content retrieval. Do not assume other .md files stored elsewhere in your libraries will be retrieved and interpreted the same way.
AI Skills for SharePoint moved to General Availability early July 2026. SHAREPOINT.md support arrived as part of the same feature wave. If your tenant has received the GA rollout, the capability is available now.
Where SHAREPOINT.md makes a tangible difference
Practically speaking, where will this capability make the most sense? Well, the following are examples of the kinds of sites where generic AI responses would cause the most friction:
HR Personnel Files and Employment Contracts
The HR Personnel Files scenario is a strong candidate for SHAREPOINT.md precisely because the processes are function and activity specific (not standard) and the consequences of wrong guidance are significant. Beyond contract creation, a well-written context file also handles questions about performance review cycles, document retention categories, and who is permitted to access which library - all areas where a generic SharePoint answer is actively unhelpful.
Policy and Compliance Libraries
Organisations with policy libraries often use site-specific naming conventions, classification schemes, and review cycles. A context file can encode the naming standard (e.g. POL-HR-001), define classification terms as the organisation uses them, and instruct the AI to always direct users to the Compliance team for questions about regulatory applicability. The result is consistent, governed guidance rather than generic document search responses.
Project and Programme Sites
Programme sites typically have custom lists, status columns, and review stages that are meaningless to a generic AI. Documenting the status taxonomy, the relationship between lists, and the standard gate review process allows the AI to answer questions like "which projects are awaiting sign-off?" accurately, rather than returning a generic list query or misinterpreting a custom status field.
Onboarding and Knowledge Transfer
Onboarding sites benefit significantly from a context file that maps the site's structure and explains what each library contains. New starters can ask natural-language questions and receive guided answers based on the team's actual conventions, rather than relying on a senior colleague to explain context that was never written down. The context file encodes institutional knowledge once; every new team member inherits it.
Communication and Marketing Content Production
Here SHAREPOINT.md provides the site-level grounding that makes Skills for article drafting, outline generation, and quality review work with consistent, brand-aware context. The file can encode house style, reading level, tone requirements, and banned terms - so that every Skill-driven output and every ad hoc prompt respects the same editorial standards.
Intake (submissions) and Triage Sites
Sites serving as intake queues, where submissions arrive via lists or libraries and are routed to subsequent stages, benefit from a context file that maps the intake structure and triage rules. Users asking "where is my request?" or "what happens after submission?" receive answers grounded in the actual intake workflow, not a generic SharePoint explanation of lists and views.
Facilities and Asset Management
Sites managing physical assets, bookings, or maintenance requests often have custom columns and lookup relationships that a generic AI cannot interpret correctly. A context file that defines status values, explains which lists feed into which workflows, and sets out what users should do at each stage transforms a confusing multi-list environment into one where AI guidance is reliable.
Regulatory and Audit-Ready Document Stores
Regulated environments require precise language about what content is in scope, who may access it, and what users must or must not do. SHAREPOINT.md supports hard rules, explicit prohibitions alongside permitted actions, that the AI applies consistently across every interaction. A context file on a clinical or legal document site can instruct the AI to never imply approval or compliance status and to always route users to the designated reviewer for regulatory questions.
Where it adds little value
SHAREPOINT.md is a passive context mechanism. It does not execute actions, trigger workflows, or retrieve content from external systems. There are a number of scenarios where it adds little to what the AI already delivers. Below are some of the most common:
Highly generalised sites with no site-specific conventions. If a site contains generic shared documents or unstructured team content with no special interpretation required, the investment in authoring a context file is hard to justify.
Cross-site processes. Where a process spans multiple sites, the single-site scope of SHAREPOINT.md is a structural limitation. The AI on Site A cannot benefit from context loaded on Site B. Cross-site orchestration requires a different approach, most likely using Copilot Studio with explicitly configured knowledge sources.
High-volume document retrieval across large libraries. There are platform constraints on how the AI processes very large knowledge sources when asked to iterate across every document individually. SHAREPOINT.md improves response quality; it does not change the retrieval model's throughput limits.
Automation and integration. The context file cannot trigger Power Automate flows, write to external systems, or call APIs. These require Skills, connectors, or Copilot Studio. SHAREPOINT.md prepares the AI to guide users through processes; it does not execute them.
Sites where structured search is the primary use case. Where users need filtered, metadata-driven search results and are comfortable with the standard SharePoint search experience, a context file does not meaningfully improve that experience.
A practical starting point
Actions worth prioritising on your most actively used Copilot in SharePoint site:
Activate the Agent Assets feature on the site.
Work through the site identity, library map, and any naming conventions
Check process guardrails relevant to the most common user questions
and capture them in a structured SHAREPOINT.md.
Upload the file and test immediately.
On a process-heavy site, the improvement in response quality is typically visible on the first chat after activation.
Future Investment
The most compelling evolution ahead would be context files at hub and tenant level, allowing organisation-wide terminology, standard policies, and shared acronyms to be defined once rather than maintained across every site independently. That capability does not yet exist, but it is the natural next step as site-level adoption matures.
If you are already using Skills, then SHAREPOINT.md is not optional - It is the foundation Skills depend on to work accurately. Write it first.
Resources
The SharePoint.md file, your site's context for Copilot in SharePoint | Daniel Anderson
Disclaimer:
Generative AI was used in the creation of this article for: source material research, title image generation, and first-pass quality review. All subject content was created by author, based on released information from Microsoft, acknowledge MVPs and specialists in field, and direct experience in implementation. Any errors or issues with the content in this article are entirely the author's responsibility.
Want to Know What We Know? Give Us a Call!
Looking for guidance in adopting Generative AI and Agents in a robust and useful manner? Or interested in learning how to adopt them into day-to-day office productivity, or even just learn some of the tricks of the trade? Email us at hi@timewespoke.com
About the author: Jonathan Stuckey
Comments