sync-blocker-auditor

Audits SharePoint libraries for file names and paths that break OneDrive sync.

128|50|Updated May 4, 2026
One-click install
npx skills add https://github.com/pnp/sharepoint-skills --skill sync-blocker-auditor-pnp
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sync-blocker-auditor
Source: https://github.com/pnp/sharepoint-skills/tree/main/Skills/sync-blocker-auditor/sync-blocker-auditor
Command: npx skills add https://github.com/pnp/sharepoint-skills --skill sync-blocker-auditor-pnp

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? SharePoint accepts file and folder names that OneDrive sync, File Explorer, and the Teams Files tab later refuse to handle, causing sync failures that surface one user at a time with no visibility into how widespread the problem is. ## Core Features & Use Cases - Rule-Based Detection: Flags illegal characters, leading/trailing spaces, trailing periods, Windows reserved names, URLs over 400 characters, deep nesting, long-term check-outs, and junk artifacts across Blocker, Risk, and Info severities. - Safe Rename Proposals: Generates a proposed safe name for every blocked item without ever modifying the library, since the audit is strictly read-only. - Self-Contained HTML Report: Produces a severity-ranked report with sync readiness score, rule frequency chart, path-length analysis, and a prioritized remediation list saved to a Sync Reports folder. - Use Case: When users report "why won't this library sync" after a migration, run the audit on the affected library to get a full inventory of the 36 blocked items, their proposed renames, and the folders causing the most failures. ## Quick Start Ask Copilot in SharePoint to run a sync health check on the document library that is failing to sync.

Frequently Asked Questions about sync-blocker-auditor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find files that break OneDrive sync in SharePoint?▼

Run a sync blocker audit on the affected document library. It recursively scans every file and folder, flags illegal characters, reserved names, and over-length paths, and produces a severity-ranked HTML report with a proposed safe name for each blocked item.

What characters are not allowed in SharePoint and OneDrive file names?▼

Names cannot contain " * : < > ? / \ |, cannot start or end with spaces, cannot end with a period, and cannot use reserved Windows device names like CON, PRN, AUX, NUL, COM0-9, or LPT0-9. Names starting with ~$ or containing _vti_ are also blocked.

What is the file path length limit in SharePoint and OneDrive?▼

The full decoded URL is limited to 400 characters in SharePoint Online, while individual file or folder names are limited to 255 characters. File Explorer and Office desktop apps impose a stricter 260-character Windows path limit that fails earlier.

Does the sync audit rename or fix the files it finds?▼

No, the audit is strictly read-only and never renames, moves, deletes, or checks in any item. It only proposes safe names in the report for human approval, and the only thing it writes is the HTML report file.

Why do invalid file names exist in SharePoint if they are blocked?▼

SharePoint enforces naming rules at upload and rename time, but content arriving through migrations, the API, or third-party tools bypasses that enforcement. These items then fail later in the OneDrive sync client and File Explorer.