Why putting everything into one skill file confuses the AI — and how reference files let you load context only when you need it.
Takeaway 1
A skill is a reusable instruction package the AI loads on a trigger phrase.
Takeaway 2
Every byte you put in the skill file lives in the context window — even when it isn't needed.
Takeaway 3
Reference files split optional context out of the main skill, so it loads only when the run actually requires it.
What is an AI Skill in SharePoint?
An AI Skill is a named, reusable instruction package the SharePoint agent can run. You write the instructions once in a skill.md file, give the skill a trigger phrase or intent, and the agent loads those instructions when a user invokes it. Think of skills as the AI equivalent of macros or saved procedures — you describe the work, the agent does it.
A skill is reusable, named instruction. The trigger phrase pulls the skill file into the conversation; the model then follows what the file says.
Skills are stored per SharePoint site in the Skills Library. The author writes the skill, sets who can use it, and from then on any matching utterance — like "super simplify this paragraph" — calls the skill instead of free-form chat.
A skill is not a finished program or a hard-coded workflow. It is plain-language instructions the AI follows at runtime. You can edit the skill in seconds and the behavior changes immediately.
The Context Window Problem
Every conversation with the AI fits inside a fixed-size memory called the context window. When the agent loads a skill, the entire content of skill.md goes into that window. If you stuff every template, example, and edge-case rule into one file, you fill the window with stuff the model doesn't need for this specific run.
More context is not better. Irrelevant context confuses the model and crowds out the room it has to actually reason about the user's request.
The video author puts it bluntly: "Do everything in your power to put as little into the context window as you can." Extra information adds noise. Noise hurts accuracy. The fix is to split what's optional out of the main file.
People think "the AI is smart, it will just ignore the parts it doesn't need." It won't. The model weighs everything in the window. Unrelated rules and templates bias its decisions in subtle ways.
Reference Files — Storage Without Cost
A reference file is a separate Markdown file that lives next to your skill but is only pulled into the conversation when the skill explicitly asks for it. The main skill.md stays small. It tells the agent: "If the user asks for a launch readiness scorecard, load references/scorecard-template.md. If it's a meeting briefing, load the briefing template instead."
References turn optional context into pay-per-use. The file exists on disk but only enters the context window when the run actually needs it.
In the demo, the author has three templates — scorecard, briefing, and what-if scenario — all sitting as separate reference files. The skill chooses one based on what the user asked for. If the user wants a scorecard, the briefing template never loads. Cleaner context, sharper output.
The pattern works because the agent reads the main skill first, decides which path applies, then fetches only the matching reference file. You get the breadth of a big knowledge base with the focus of a tiny prompt.
Build skills this way whenever the same trigger handles multiple variants. Common variants worth splitting into references: report templates, persona-specific tone guides, table schemas, validation rules, and long examples that only one workflow needs.
Rule of thumb — if a chunk of the skill file would only be used in 1 in 4 runs (or fewer), move it to a reference and conditionally load it.
"References slow the skill down by adding a file fetch." The fetch is cheap. The wins from a smaller, focused context window almost always outweigh the milliseconds of disk read.
Flashcards — Foundations
01 · Foundations
AI Skill
tap to reveal →
A named, reusable instruction package stored in SharePoint. A trigger phrase loads the skill's Markdown file into the agent's context so it follows those instructions for the run.
← tap to flip back
01 · Foundations
Context Window
tap to reveal →
The fixed-size memory the model uses for a single run. Everything loaded — system prompt, skill file, references, chat history — competes for the same finite space.
← tap to flip back
01 · Foundations
skill.md
tap to reveal →
The main Markdown file that defines a skill. Keep it small — list the trigger, the high-level behaviour, and pointers to reference files instead of inlining every template.
← tap to flip back
01 · Foundations
Reference File
tap to reveal →
A side file the skill loads only when needed. Templates, schemas, and long examples live here so they don't sit in every run's context window.
← tap to flip back
01 · Foundations
Lazy Context Loading
tap to reveal →
The discipline of pulling rules, templates, or data into the context window only when the current run actually requires them — the foundation of clean skill design.