skills-vault/skills/repair-markdown-citations/SKILL.md

name	description
repair-markdown-citations	Use when a Markdown export from ChatGPT Deep Research or another LLM contains broken citation tokens such as `citeturn34view0turn20search2` that need to be converted into standard Markdown footnotes and a deduplicated `## 参考资料` section. Use for repairing turn-ID citations, cleaning citation mojibake, preserving source links, and safely degrading when metadata is missing.

Repair Markdown Citations

Purpose

Repair ChatGPT/Deep Research Markdown citation tokens into readable Markdown. Use the bundled script for deterministic edits instead of rewriting the document by prompt.

The primary rule is exact ID mapping: treat turn34view0, turn20search2, and similar IDs as citation primary keys. Do not assume the citation token order matches safe_urls, a footer link list, or source appearance order.

Capability Levels

Level 1: no metadata cleanup.

• Remove malformed cite... tokens outside fenced code blocks.
• Preserve existing links from an old ## 参考资料 section as ordinary source links.
• Add a warning that逐句脚注映射 could not be recovered.

Level 2: content_references metadata.

• Build a citation map from metadata refs keyed by turn ID.
• Replace citation tokens in正文 with Markdown footnote markers such as [^1][^2].
• Generate a deduplicated ## 参考资料 section in first-citation order.

Level 3: complete Deep Research export.

• Prefer exact ref_id / turn_index / ref_type / ref_index fields wherever available.
• Use richer fields such as title, attribution, source, and site name when present.
• Treat source grouping, dates, snippets, and risk checks as future enrichment, not required first-pass behavior.

Workflow

1. Confirm the input is a Markdown file exported from ChatGPT/Deep Research or converted from a report containing citation tokens.
2. Prefer an explicit metadata JSON file. If the user has one, pass it with --metadata.
3. If no metadata file is available, let the script look for an embedded HTML comment block named deep-research-metadata.
4. Choose output mode:
   • Use --output for a non-destructive repaired copy.
   • Use --in-place only when the user wants the original file rewritten.
   • Use --dry-run before editing important files.
5. Inspect the resulting ## 参考资料 section and any 未解析引用 ID warnings.

Commands

conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --metadata "C:\path\report.metadata.json" --output "C:\path\report.fixed.md"
conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --metadata "C:\path\report.metadata.json" --in-place
conda run -n skills-vault python .\scripts\repair_markdown_citations.py "C:\path\report.md" --dry-run

Embedded Metadata

The script can read a Markdown HTML comment block:

<!-- deep-research-metadata
{"content_references":[...]}
-->

Use embedded metadata only when an external JSON file is unavailable or when the report intentionally carries its own citation map.

Safety Rules

• Do not map citations by safe_urls order or by footer link order.
• Do not fabricate footnotes when a turn ID has no URL in the citation map.
• Do not rewrite citation-like text inside fenced code blocks.
• Do not delete user-authored prose or non-reference sections.
• If metadata is missing or incomplete, preserve recoverable source links and clearly mark the output as degraded.

Validation

Run the Skill tests after modifying behavior:

conda run -n skills-vault python -m unittest discover -s skills/repair-markdown-citations/tests -v