read-sharepoint

beta

Reads and converts SharePoint files (.xlsx, .docx, .pptx, .xls, .doc, .ppt) to markdown using the M365 CLI. Use when the user says 'read from SharePoint', 'fetch a document from SharePoint', 'browse the Projects folder', 'download from SharePoint', 'search SharePoint for...', or provides a SharePoint URL (velaisfzco.sharepoint.com). Also triggers on 'get the spreadsheet from SP', 'pull that file from the company site', or 'what's in the Projects folder'. Do NOT use for uploading files to SharePoint, editing SharePoint pages, managing SharePoint permissions, or converting local Office files without a SharePoint context.

Owner: velais Category: workflow-automation Version: 1.0.0 Tokens: ~5k

sharepointm365officeexcelwordpowerpoint

Quality Score Breakdown

Structure (15%) 18/18

Show checks (11)

✓ SKILL.md exists with exact casing 3/3
✓ Valid YAML frontmatter 3/3
✓ No unexpected frontmatter keys 1/1
✓ Name field valid (kebab-case) 2/2
✓ Name matches folder name 1/1
✓ Description field present 2/2
✓ No angle brackets in frontmatter 1/1
✓ Folder name is kebab-case 1/1
✓ No README.md inside skill folder 1/1
✓ Test directory with test-cases.yml exists 2/2
✓ Status 'beta' is valid 1/1

Description (20%) 20/22

Show checks (7)

✓ Contains action verbs: converts 2/4
✓ Contains trigger indicators: use when, use for, trigger, says 5/5
✓ Description is specific and actionable 4/4
✓ File types mentioned in description 3/3
✓ Description length: 626/1024 chars 2/2
✓ Has negative triggers (scope boundaries) 2/2
✓ Owner/author specified in metadata 2/2

Instructions (25%) 28/28

Show checks (8)

✓ Skill body has content 3/3
✓ Has step/section structure 4/4
✓ Includes examples 5/5
✓ Includes error handling 4/4
✓ Uses progressive disclosure (references/scripts) 4/4
✓ Actionable language: 6/10 verb patterns found 3/3
✓ Word count: 758/5000 2/2
✓ All referenced paths exist 3/3

Test Coverage (25%) 29/29

Show checks (10)

✓ test-cases.yml exists and parses 3/3
✓ 6 should-trigger tests ✓ 4/4
✓ 3 should-not-trigger tests ✓ 3/3
✓ 6 functional tests ✓ 5/5
✓ 2 negative tests ✓ 3/3
✓ 3 edge case tests ✓ 3/3
✓ Performance baseline documented 2/2
✓ All functional tests have ≥2 assertions 2/2
✓ All trigger phrases are diverse 2/2
✓ All assertions are specific 2/2

Security (15%) 14/15

Show checks (5)

✓ No secrets detected 5/5
✓ No injection vectors in frontmatter 3/3
✓ Name is not reserved 3/3
✓ No suspicious code patterns 2/2
✗ 12 external URLs found — verify they're necessary: https://velaisfzco.sharepoint.com/sites/company, https://velaisfzco.sharepoint.com/sites/company, https://velaisfzco.sharepoint.com/sites/company 1/2

Test Coverage

Should Trigger

Should Not Trigger

Functional

Negative

Edge Cases

LLM Evals

Read SharePoint Files

Reads files from SharePoint, downloads them via the M365 CLI, and converts Office documents (Excel, Word, PowerPoint) to readable markdown.

Defaults

The default SharePoint location is the Velais company Projects library:

Site URL: https://velaisfzco.sharepoint.com/sites/company
Projects folder: /sites/company/Projects
M365 login: m365 login --appId b73ce108-03e1-4bf2-bbbf-0b48e50f73e1 --authType browser --tenant velais.com

When the user asks to read a file without specifying a full path, search within this default location first.

Step 1 — Preflight Check

Run the preflight checker to validate all dependencies:

python scripts/preflight.py

This checks for Python 3.10+, required pip packages (pandas, openpyxl, python-docx, python-pptx), the M365 CLI, and active M365 authentication.

If any checks fail, show the user the output and stop. Guide them through the setup instructions shown in the output. Do NOT proceed to later steps until preflight passes.

If preflight passes, continue to Step 2.

Step 2 — Find the File

If the user specified a filename or partial path, search within the default Projects folder first:

# List files in a specific project subfolder (default site)
m365 spo file list --webUrl "https://velaisfzco.sharepoint.com/sites/company" --folderUrl "/sites/company/Projects/<subfolder>" --output json

# Or search across all sites if not found in the default location
m365 spo search --queryText '"<filename>" IsDocument:1' --selectProperties "Title,Path,Size,LastModifiedTime,FileExtension" --rowLimit 10 --output json

To browse the folder structure:

# List project folders
m365 spo folder list --webUrl "https://velaisfzco.sharepoint.com/sites/company" --parentFolderUrl "/sites/company/Projects" --output json

# List files recursively in a project folder
m365 spo file list --webUrl "https://velaisfzco.sharepoint.com/sites/company" --folderUrl "/sites/company/Projects/<subfolder>" --recursive --output json

If the user provides a different site URL or wants to search outside the default, use that instead.

Present the results clearly and let the user confirm which file(s) to download.

Step 3 — Download

Download the confirmed file(s) using the M365 CLI directly:

mkdir -p /tmp/sp_downloads
m365 spo file get --webUrl "https://velaisfzco.sharepoint.com/sites/company" --url "<server_relative_url>" --asFile --path "/tmp/sp_downloads/<filename>"

Create the output directory first if needed. The CLI handles files of any size.

Step 4 — Convert

Convert the downloaded file(s) to readable markdown:

python scripts/convert.py "<downloaded_file_path>" --output-dir /tmp/sp_converted

This produces:

Excel: One .md file per worksheet, with data as markdown tables
Word: One .md file preserving headings, paragraphs, lists, and tables
PowerPoint: One .md file with each slide as a section, including speaker notes

Step 5 — Present

Read the converted .md file(s) and present the content to the user. For Excel files with multiple sheets, briefly summarise what each sheet contains before diving into detail.

If there are multiple output files, read them all and give the user a clear overview.

Converted files are written to /tmp/sp_converted — mention this location so the user can find them later.

Error Handling

Auth Expired

If the M365 CLI returns an authentication error, tell the user to re-authenticate:

m365 login --appId b73ce108-03e1-4bf2-bbbf-0b48e50f73e1 --authType browser --tenant velais.com

Then retry the failed command.

Legacy Formats (.doc, .ppt)

The converters attempt to handle .doc and .ppt files, but python-docx and python-pptx may not support these legacy formats reliably. If conversion fails, warn the user and suggest they open the file in SharePoint and save it as .docx or .pptx first.

Preflight Failures

If preflight fails, do NOT attempt to proceed with partial tooling. The preflight output includes specific setup instructions for each missing dependency. Walk the user through those instructions before retrying.

File Not Found

If the file is not found in the default Projects folder, broaden the search using m365 spo search across all sites. If still not found, ask the user to verify the filename or provide a direct SharePoint URL.

Examples

Example 1: Read an Excel file from a project folder

User: “Read the Q4 budget spreadsheet from the Velais-Internal project”

Expected workflow:

Run python scripts/preflight.py — all checks pass
List files in /sites/company/Projects/Velais-Internal to find the budget file
User confirms Q4_Budget_2025.xlsx
Download with m365 spo file get to /tmp/sp_downloads/Q4_Budget_2025.xlsx
Convert with python scripts/convert.py — produces one .md per sheet
Read and present: “This workbook has 3 sheets: Summary, Revenue, Expenses. Here’s the Summary…”

Example 2: Search for a Word document across SharePoint

User: “Find the onboarding guide on SharePoint”

Expected workflow:

Run python scripts/preflight.py — all checks pass
Search: m365 spo search --queryText '"onboarding guide" IsDocument:1'
Results show Onboarding_Guide_2025.docx in /sites/company/HR/Documents
User confirms the file
Download and convert to markdown
Present the document content with headings and structure preserved