Sync Blocker Auditor

Step 4 — Compute the scores

• Sync readiness % = items with no Blocker ÷ total items scanned, as a whole number.
• Counts of Blocker / Risk / Info items (an item counts once, at its highest severity).
• Rule frequency — how many items matched each rule ID, sorted descending.
• Folder hot spots — the folders containing the most affected items.
• Longest URL — the single worst path, with its character count.

Step 5 — Build a self-contained HTML report

Draft one self-contained HTML file:

• No scripts. No external CSS, fonts, images, or resources. Inline CSS only.
• Summary band — items scanned, sync readiness %, Blocker / Risk / Info counts, longest URL length, and the single most common rule.
• Severity strip — three coloured cards: Blocker (red #b3261e), Risk (amber #a16207), Info (blue #1e40af).
• Rule frequency chart — one row per matched rule showing rule ID, plain-English label, and a horizontal bar drawn with inline-CSS width (e.g., a coloured <div> at width: 62%), coloured by the rule's severity.
• Findings table — one row per affected item: name, folder path, severity badge, matched rule IDs, a plain-English reason, and the proposed safe name. Sort Blockers first.
• Path-length table — the 10 longest URLs with their character counts, each drawn as a bar against the 400-character SharePoint limit, with the 260-character Windows limit marked so it is obvious which items already break the desktop clients.
• Checked-out table — file, who has it checked out, and for how many days (omit the section entirely if there are none).
• Folder hot spots — the folders with the most affected items.
• Remediation list — a short, prioritised, plain-English list, most impactful first ("Rename 12 files containing : — sync fails for every user", "Flatten Projects/2026/Q3/... — 6 files are within 40 characters of the URL limit").
• Limitations section — only if any data was unavailable or the scan was partial.

Keep percentages as whole numbers and be consistent throughout the report.

Step 6 — Save the report

• Save the HTML file in a Sync Reports folder in the site's default Documents library (or Site Assets). Never write into the library under audit unless the user explicitly asks — writing a report into the audited scope changes the very thing that was just measured, and the reports accumulate as findings on the next run.
• Create the Sync Reports folder only if it does not exist, and only to hold the report.
• Use a clear filename: Sync-Blocker-Audit-<Library>-YYYY-MM-DD-HHMM.html.
• If the save fails because the user lacks write access anywhere on the site, do not stop — say the report could not be saved, and return the full findings inline as Markdown instead.

Step 7 — Respond to the user

After saving, reply with a compact Markdown summary and the report link:

# Sync blocker audit complete

[Open the report](<link>)

- Scope: <library / folder audited>
- Items scanned: <n> (<n> files, <n> folders)
- Sync readiness: <n>%  (Blockers <n> · Risks <n> · Info <n>)
- Top blocker: <rule label> on <n> items
- Longest URL: <n> characters (limit 400)

Example

User: "Why won't the Project Files library sync?"

Agent response after processing:

I audited Project Files (412 items — 366 files, 46 folders) against the OneDrive sync and URL rules.

Metric	Result
Sync readiness	91%
Blockers / Risks / Info	36 / 58 / 9
Top blocker	Illegal characters (B1) on 21 items
Longest URL	438 characters (limit 400)

The worst offender is Clients/Northwind/Contracts/Q3: Signed & Approved/ — the : in that folder name blocks every one of the 14 files inside it for every synced user.

I saved the report to Sync Reports/Sync-Blocker-Audit-Project-Files-2026-08-20-1130.html, including a proposed safe name for all 36 blocked items. Nothing was renamed.

Constraints

• Strictly read-only. Never rename, move, delete, check in, check out, or modify any item, folder, column, view, or setting. The only thing this skill writes is the HTML report file (and, if needed, the Sync Reports folder to hold it).
• Never fabricate items, paths, names, or check-out owners — everything comes from the actual library.
• Rename suggestions are proposals only. Always present them for human approval and state explicitly that nothing was changed.
• Measure URL length against the full decoded URL, not the file name alone, and always state the limit next to the number — 400 characters for SharePoint (B7), 260 for Windows (R2).
• Compute lengths, character matches, and totals with execute_code. Never estimate a character count by inspection.
• Report technical blockers only. Do not flag names for being vague, generic, or unhelpful.
• Page through the entire library; report partial results plainly if a tool fails.
• The HTML report must be fully self-contained: no scripts, no external resources, inline CSS only.
• Match on names case-insensitively, but always display the original name exactly as stored, including the whitespace that caused the finding (wrap such names in ` so trailing spaces stay visible).

References

• Restrictions and limitations in OneDrive and SharePoint — the disallowed names (.lock, desktop.ini, ~$…, _vti_, root forms) and the TMP-files behaviour behind B5, B6, and R6.
• What are the file path length limits? — the 400-character decoded-path limit (B7), the 255-character per-name limit (B8), and the 260-character Windows limit (R2).
• SharePoint Online limits

The illegal-character, whitespace, and trailing-period rules (B1–B3) are enforced by SharePoint and Windows at upload and rename time rather than being listed in the article above. They matter because content that arrived through migrations, the API, or third-party tools bypassed that enforcement — which is why these names exist in real libraries at all.