Repair the rest of what Google's export does to frontmatter

[henry-dowling]

our google drive to skills conversion uses the google drive "export to markdown" feature to convert docs to skills, which are markdown files by default. Unfortunately, this export mangles a bunch of things about the doc in the conversion, so we need to manually fix them. This is a surgical fix, we only go ahead with this manual un-mangling when the result will be a valid skill (we think in this case, it's clearly a good thing for us to do this). We also include a migration to repair already-broken already-imported markdown files from drive.

Thanks to @mholkesvik for the find

slop

Stacked on #1043. The escaped --- that #1040 repairs was the fatal shape, but not the only one — a skill authored in a Doc is prose on the way in and markdown on the way out, and the exporter marks up characters the author never typed.

Four shapes, all invisible in the editor, found by running real export shapes through the extractor and the skill parser:

What the author sees in the Doc	What the export stores	Before this PR
name: "Brake Shoes" (typed, so Docs curls it)	name: “Brake Shoes”	parses, and the skill is named “Brake Shoes” — quotes included
description: "...part_number..."	...part\_number...	\_ is not a valid JSON escape, so json.loads throws, declared_skill swallows the ValueError, and the document silently isn't a skill
name: styled bold	**name:**	partitions to a key nothing is looking for
an empty first paragraph above the block	a leading blank line	fatal twice: the block is no longer at the top, and list_source_skills filters on content LIKE '---%' before anything parses

Repaired at extraction, beside the rule fix and for the same reason given there: the markup belongs to the exporter, not the author or the format. Escaped rules are still repaired anywhere in the document; the rest only between the delimiters, because frontmatter is the one region with no markup in it — a \_ or a ** below the block is the author writing markdown and stays. Only the wrapping quote pair is straightened, so a curly apostrophe mid-sentence is left as their text.

Context: this is the failure mode Heavi flagged in Slack ("weird Google Docs formatting stuff that messed up frontmatter"), and the curly-quote row is the likeliest one to bite them — the example we handed them is quoted, and Docs curls a typed quote by default.

Verification

• 6 new tests in test_drive_extraction_pipeline.py, including one asserting the body below the block is not rewritten (that text is what the agent reads).
• pytest backend/tests/test_drive_extraction_pipeline.py — 31 passed. With test_source_backed_skills, test_skill_metadata, test_every_skill_creation_path, test_folder_skills, test_skill_agent_read, test_github_skill_import: 86 passed, 0 failed.
• ruff check backend/ cli/ and ruff format --check backend/ cli/ clean.

Not covered

• No live Drive round-trip. Every shape here is constructed, not observed coming back from the API — unlike the \--- fix, which was verified end to end against a real Doc. Worth one live check before this ships.
• A UTF-8 BOM is not handled. If Drive's export ever emits one it fails the same LIKE '---%' prefilter as the blank-line case. Left alone rather than guessed at.

🤖 Generated with Claude Code

---

Note

Medium Risk
A one-time migration rewrites user document content in drive_documents with strict guards, but incorrect filtering could corrupt stored text; extraction changes what gets stored for all Google Doc exports going forward.

Overview
Extends Google Doc → markdown extraction so skills authored in Docs can declare valid frontmatter after export. unescape_exported_rules is replaced by repair_exported_frontmatter, which still fixes escaped --- rules but also normalizes delimiter blocks (BOM/leading blanks, --- normalization), strips exporter emphasis from keys, unescapes CommonMark punctuation in values, and re-encodes curly-wrapped quotes as JSON strings. Repairs apply only inside a detected frontmatter block and the result is kept only when declared_skill succeeds, so ordinary docs that open with horizontal rules stay unchanged; markdown below the closing delimiter is not rewritten.

Migration 0186 backfills existing drive_documents.content with a frozen copy of that logic, updating rows only when the repair newly yields a valid skill or fixes curly-quoted skill metadata, and marks affected rows embed_stale. Integration tests cover export shapes; an isolated DB test asserts the backfill repairs damaged exports without touching prose or clean hand-authored SKILL.md files.

^{Reviewed by Cursor Bugbot for commit 3886660. Bugbot is set up for automated code reviews on this repo. Configure here.}

[assert-app]

Review on Assert →

3 clusters identified

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stash-web	Ready	Preview	Aug 18, 2026 8:57am

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_bef3e14b-8dd6-4a0f-96b9-f52b69a2e06f)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_bb07c314-589b-4066-a264-1fc29a7fa9f1)