A SKILL.md file can do everything itself. Instructions, steps, standards, every rule baked into one Markdown file. That works for the first one or two Skills you write, then it stops working. The file gets unwieldy. Standards that apply to several Skills get duplicated. A change in one place needs ten edits to keep the rest in sync.
The fix is reference files. SKILL.md becomes the orchestration layer. References hold the standards. The Skill loads them only when needed.
This piece walks through how I structure Skills with references, where the files live, and a real example from a proposal reviewer Skill.
If Skills are new, read what SharePoint AI Skills are and the pillar on extending SharePoint AI with Skills first. This piece assumes you have shipped at least one Skill and want to take the next step.
Why split content out of SKILL.md
Two reasons.
The first is reuse. A standards file for proposals can serve a proposal review Skill, a proposal QA Skill, and a proposal-writing assistant. If those standards live inline in three different SKILL.md files, an update means three edits and the chance that one falls out of sync. If the standards live in one reference file, every Skill that calls it picks up the change automatically.
The second is readability. A SKILL.md file with every guideline inline becomes a wall of text. Hard to review, hard to debug. Pulling content out of SKILL.md keeps the orchestration layer focused on what the Skill does and when, and pushes the supporting detail somewhere it can be read on its own terms.
Where reference files live
References live in a subfolder under the Skill folder. The convention I follow is references/.
/Agent Assets/Skills/Proposal Reviewer/
├─ SKILL.md
└─ references/
└─ proposal-standards.md
The path matters because SKILL.md needs to reference it when loading. The folder name does not have to be references strictly, but the convention helps anyone reading the Skill later.
For details on how Skills are stored and governed, see Microsoft Learn on extending AI in SharePoint with Skills.
How SKILL.md loads a reference
AI in SharePoint exposes a tool called load skills that lets a Skill load other Skills or files from the Agent Assets library. SKILL.md describes when to use it and which file to load.
A simplified example from the proposal reviewer Skill:
## When invoked
When a user shares a proposal or paste it.
## Steps
1. Use the load skills tool with skill name "Proposal Reviewer"
and file path "references/proposal-standards.md" to get
the current review criteria.
2. Read the proposal the user provided.
3. Compare against the standards. Flag every issue against
the must-fix and should-fix categories.
4. Return a structured review with each flagged item, the
standard it violates, and a recommended fix.
When the Skill runs, it loads the standards file, reads the proposal, applies the rules, and produces the review. The standards live where they belong: in a file dedicated to standards, editable on its own, reusable across Skills.
A real example: the proposal reviewer Skill
The proposal reviewer Skill on a client site I work on does exactly this. SKILL.md is short. References do the heavy lifting.
SKILL.md describes the trigger ("review proposal" or "run proposal review"), the inputs (a selected proposal file), and the steps (load standards, read proposal, compare, return). It is around 40 lines.
references/proposal-standards.md holds the actual review criteria. Positioning rules. Guardrails for language to avoid. Mandatory inclusions every proposal must have. Commitments the firm never makes. Engagement size minimums. Payment terms. The file is much longer than SKILL.md, and every line is content rather than orchestration.
When the Skill runs against a proposal, the output is a structured review with three categories: must fix, should fix, and observations. Each flagged item maps back to a specific line in the standards file, so the reviewer (and the proposal author) can see exactly which rule was triggered.
The same proposal-standards.md reference is also called by a separate proposal-drafting Skill that another team uses. Both Skills load the same file. When the standards change (new clause language, updated minimums), one file gets edited and both Skills pick up the change.
When references earn their keep
References are not free. They add a level of indirection. The trade-off is worth it when:
- The content is reused across more than one Skill.
- The content is large enough that pulling it out makes SKILL.md easier to read.
- The content changes more often than the orchestration logic. Standards drift; the workflow stays stable.
If a piece of content is unique to one Skill and small, leave it in SKILL.md. The convention is there to be broken when the situation calls for it.
Where to take this next
Look at your existing Skills. Find the content in any SKILL.md that is duplicated in another, or that is large enough to be hard to read. Pull it into a reference file. Update the calling SKILL.md to load the reference instead.
The Skill behaviour stays the same. The maintenance gets significantly easier. The next Skill you write starts cleaner because the standards file is already there.