[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6HXG86P3JFSJ6Y1RXP1A024":3,"skill-same:01M6HXG86P3JFSJ6Y1RXP1A024":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":54,"ownerDescription":6,"updatedAt":55,"install":56,"resources":69},"01M6HXG86P3JFSJ6Y1RXP1A024","doc-gen-unicode-diagnostic",null,"Systematic document generation with unicode sanitization, engine fallback chain, and explicit error diagnosis","HKUDS\u002FAgentPilot","HKUDS","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F118165258?v=4","01M6HW8VRNZP64G0P4MVJW2KKQ","✨Data Intelligence Lab@HKU✨","01M6HW8VWZVHBRHYH3T330PFWV",8029,"MIT","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced-3d3a9a\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"doc","Unicode","diagnostic","doc gen","doc gen unicode diagnostic","engine","fallback","document","generation","systematic","diagnosis","chain","error","document generation","with","sanitization","2026-11-10 10:12:30",false,"---\nname: doc-gen-unicode-diagnostic\ndescription: Systematic document generation with unicode sanitization, engine fallback chain, and explicit error diagnosis\n---\n\n# Document Generation with Diagnostic Workflow (Unicode-Safe)\n\n## When to Use\n\nUse this skill when document generation tasks fail or return unclear errors, especially when:\n- Generating documents in multiple formats (`.docx`, `.pdf`, `.html`)\n- **PDF generation fails with encoding\u002FLaTeX errors**\n- `shell_agent` returns \"unknown error\" without diagnostics\n- Documents contain special characters, symbols, or non-ASCII text\n- You need systematic error diagnosis rather than blind retries\n\n## ⚠️ Critical: Why This Skill Exists\n\nRecent executions show **43% effectiveness** because agents:\n- Skip unicode sanitization before PDF conversion\n- Don't try `xelatex` engine (better Unicode support)\n- Don't capture stderr for proper diagnosis\n- Exhaust iterations on repeated failures without systematic troubleshooting\n\n**This skill fixes those gaps with mandatory steps.**\n\n## Pre-Flight Validation (NEW - Required Step 0)\n\nBefore starting document generation, verify your toolchain:\n\n```\nrun_shell\ncommand: which pandoc && pandoc --version | head -3\n```\n\n```\nrun_shell\ncommand: which pdflatex xelatex wkhtmltopdf 2>\u002Fdev\u002Fnull || echo \"Some engines missing\"\n```\n\n```\nrun_shell\ncommand: python3 -c \"import sys; print(sys.version)\"\n```\n\nIf pandoc is missing, install it:\n```\nrun_shell\ncommand: apt-get update && apt-get install -y pandoc\n```\n\nFor PDF support, install LaTeX engines:\n```\nrun_shell\ncommand: apt-get install -y texlive-latex-recommended texlive-fonts-recommended texlive-xetex\n```\n\n## Core Technique\n\n**Manually split the workflow into observable, diagnostic steps:**\n1. **Pre-flight** → Verify toolchain availability\n2. **Content creation** → Use `write_file` for markdown source (visible content)\n3. **Unicode sanitization** → **MANDATORY for PDF**: Create sanitized version\n4. **Format conversion with fallback** → Try engines in order, capture stderr\n5. **Verification** → Check outputs exist and validate content\n\n## Unicode & LaTeX Compatibility (MANDATORY for PDF)\n\n**PDF generation via LaTeX has limited Unicode support.** Before PDF conversion, you MUST sanitize:\n\n| Character | Issue | Safe Replacement |\n|-----------|-------|------------------|\n| `—` (em dash) | LaTeX incompatibility | `--` |\n| `–` (en dash) | LaTeX incompatibility | `-` |\n| `\" \"` (curly quotes) | Encoding errors | `\" \"` (straight) |\n| `' '` (curly apostrophe) | Encoding errors | `'` (straight) |\n| `…` (ellipsis) | May not render | `...` |\n| `→` `←` `↑` `↓` (arrows) | LaTeX incompatibility | `->` `\u003C-` `^` `v` |\n| `✓` `✗` (checkmarks) | May not render | `[x]` `[ ]` |\n| `★` `●` (symbols) | May not render | `*` `-` |\n| `©` `®` `™` | Require packages | `(c)` `(r)` `(tm)` |\n| Non-ASCII (é, ñ, ü) | Font-dependent | Keep for xelatex, sanitize for pdflatex |\n\n**DOCX and HTML handle Unicode natively** - use original markdown for these formats.\n\n## Step-by-Step Workflow\n\n### Step 0: Pre-Flight Validation\n\n```\nrun_shell\ncommand: which pandoc || (apt-get update && apt-get install -y pandoc)\n```\n\n```\nrun_shell\ncommand: which xelatex || echo \"xelatex not available - will use fallback\"\n```\n\n### Step 1: Create Source Content with write_file\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Your content here with full Unicode support...\n  \n  ## Section 2\n  Special chars: \"quotes\" — dashes … ellipsis ✓ checkmarks\n```\n\n### Step 2: Create Sanitized Version for PDF (**MANDATORY**)\n\n**Option A: Manual sanitization with write_file**\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source_sanitized.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Your content here...\n  \n  ## Section 2\n  Special chars: \"quotes\" -- dashes ... ellipsis [x] checkmarks\n```\n\n**Option B: Automated sanitization script**\n\nFirst create the script:\n```\nwrite_file\npath: \u002Ftmp\u002Fsanitize_for_pdf.sh\ncontent: |\n  #!\u002Fbin\u002Fbash\n  INPUT=\"$1\"\n  OUTPUT=\"${2:-${1%.md}_sanitized.md}\"\n  sed -e 's\u002F—\u002F--\u002Fg' -e 's\u002F–\u002F-\u002Fg' \\\n      -e 's\u002F\"([^\"]*)\"\u002F\"\\1\"\u002Fg' -e \"s\u002F'([^']*)'\u002F\\`\\1\\`\u002Fg\" \\\n      -e 's\u002F…\u002F...\u002Fg' -e 's\u002F→\u002F->\u002Fg' -e 's\u002F←\u002F\u003C-\u002Fg' \\\n      -e 's\u002F✓\u002F[x]\u002Fg' -e 's\u002F✗\u002F[ ]\u002Fg' \\\n      -e 's\u002F©\u002F(c)\u002Fg' -e 's\u002F®\u002F(r)\u002Fg' -e 's\u002F™\u002F(tm)\u002Fg' \\\n      \"$INPUT\" > \"$OUTPUT\"\n  echo \"Sanitized: $INPUT -> $OUTPUT\"\n```\n\n```\nrun_shell\ncommand: chmod +x \u002Ftmp\u002Fsanitize_for_pdf.sh && \u002Ftmp\u002Fsanitize_for_pdf.sh \u002Ftmp\u002Fdocument_source.md \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n### Step 3: Convert to DOCX (from original, supports Unicode)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.docx 2>&1\n```\n\n**Capture stderr** with `2>&1` to see actual errors (not \"unknown error\").\n\n### Step 4: Convert to PDF with Engine Fallback Chain (**CRITICAL**)\n\n**Try engines in order: xelatex (best Unicode) → pdflatex → wkhtmltopdf**\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=xelatex 2>&1\n```\n\nIf xelatex fails, try pdflatex:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=pdflatex 2>&1\n```\n\nIf pdflatex fails, try wkhtmltopdf:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=wkhtmltopdf 2>&1\n```\n\n**If ALL engines fail**, diagnose with:\n```\nrun_shell\ncommand: file \u002Ftmp\u002Fdocument_source_sanitized.md && head -20 \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n### Step 5: Convert to HTML (from original)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.html 2>&1\n```\n\n### Step 6: Verify All Outputs\n\n```\nrun_shell\ncommand: ls -lh output.* && file output.*\n```\n\n```\nrun_shell\ncommand: [ -f output.pdf ] && echo \"PDF created: $(wc -c \u003C output.pdf) bytes\" || echo \"PDF MISSING\"\n```\n\n## Complete Example\n\n```markdown\n# Generate Client Report in Multiple Formats\n\n## Step 0: Pre-flight\nrun_shell\ncommand: which pandoc xelatex || echo \"Checking toolchain...\"\n\n## Step 1: Write markdown source\nwrite_file\npath: \u002Ftmp\u002Fclient_report.md\ncontent: |\n  # Client Investment Report\n  \n  ## Executive Summary\n  Portfolio performance shows strong returns — up 15% this quarter...\n  \n  ## Risk Analysis\n  Key metrics: \"Sharpe ratio\" ✓ passed … continuing analysis\n\n## Step 2: Sanitize for PDF (MANDATORY)\nwrite_file\npath: \u002Ftmp\u002Fclient_report_sanitized.md\ncontent: |\n  # Client Investment Report\n  \n  ## Executive Summary\n  Portfolio performance shows strong returns -- up 15% this quarter...\n  \n  ## Risk Analysis\n  Key metrics: \"Sharpe ratio\" [x] passed ... continuing analysis\n\n## Step 3: Convert to DOCX (original unicode OK)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report.md -o client_report.docx 2>&1\n\n## Step 4: Convert to PDF (sanitized, xelatex first)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report_sanitized.md -o client_report.pdf --pdf-engine=xelatex 2>&1\n\n## Step 5: Convert to HTML (original unicode OK)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report.md -o client_report.html 2>&1\n\n## Step 6: Verify\nrun_shell\ncommand: ls -lh client_report.* && file client_report.*\n```\n\n## Error Diagnosis Decision Tree\n\nWhen a conversion fails, **capture stderr** (`2>&1`) and diagnose:\n\n```\nIf error contains \"xelatex not found\" or \"LaTeX error\":\n  → Try next engine: --pdf-engine=pdflatex or --pdf-engine=wkhtmltopdf\n\nIf error contains \"encoding\" or \"UTF-8\":\n  → Unicode not properly sanitized; re-check Step 2\n  → Add -f markdown+utf8 to pandoc command\n\nIf error contains \"template\" or \"class\":\n  → LaTeX template issue; try --pdf-engine=wkhtmltopdf\n\nIf error is \"unknown error\" (no stderr captured):\n  → Re-run with 2>&1 to capture actual error message\n  → Check if pandoc is installed: which pandoc\n\nIf wkhtmltopdf fails:\n  → Install: apt-get install wkhtmltopdf\n  → Or use Python alternative: reportlab or fpdf2\n```\n\n## Alternative: Python PDF Generation (When pandoc Fails)\n\nIf all pandoc engines fail, use Python libraries directly:\n\n**Using fpdf2:**\n```\nrun_shell\ncommand: python3 -c \"\nfrom fpdf import FPDF\npdf = FPDF()\npdf.add_page()\npdf.set_font('Arial', '', 12)\npdf.cell(0, 10, 'Document Title')\npdf.output('output.pdf')\n\"\n```\n\n**Using reportlab:**\n```\nrun_shell\ncommand: python3 -c \"\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\nc = canvas.Canvas('output.pdf', pagesize=letter)\nc.drawString(100, 750, 'Document Title')\nc.save()\n\"\n```\n\n## Common pandoc Commands Reference\n\n```bash\n# Markdown to Word (Unicode-safe)\npandoc input.md -o output.docx\n\n# Markdown to PDF with xelatex (BEST for Unicode)\npandoc input.md -o output.pdf --pdf-engine=xelatex\n\n# Markdown to PDF with pdflatex (requires sanitization)\npandoc input.md -o output.pdf --pdf-engine=pdflatex\n\n# Markdown to PDF with wkhtmltopdf (HTML-based, good fallback)\npandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf\n\n# Markdown to HTML\npandoc input.md -o output.html\n\n# With metadata\npandoc input.md -o output.pdf --metadata title=\"Document Title\"\n\n# Force UTF-8 encoding\npandoc -f markdown+utf8 input.md -o output.pdf\n```\n\n## Troubleshooting Quick Reference\n\n| Symptom | Likely Cause | Solution |\n|---------|--------------|----------|\n| \"xelatex not found\" | Missing LaTeX engine | `apt-get install texlive-xetex` or try `--pdf-engine=wkhtmltopdf` |\n| \"LaTeX error: encoding\" | Unicode in source | Use sanitized markdown for PDF |\n| \"unknown error\" (pandoc) | stderr not captured | Re-run with `2>&1` to see real error |\n| PDF missing after conversion | All engines failed | Try Python (fpdf2\u002Freportlab) as fallback |\n| DOCX has garbled text | Encoding issue | Add `-f markdown+utf8` to pandoc command |\n| HTML renders but PDF fails | LaTeX-specific issue | wkhtmltopdf engine usually works |\n\n## Verification Checklist\n\nBefore marking task complete, verify:\n\n- [ ] Pre-flight: pandoc installed and accessible\n- [ ] Source markdown created with `write_file`\n- [ ] Sanitized version created for PDF conversion\n- [ ] DOCX generated from original (unicode preserved)\n- [ ] PDF generated with xelatex (or fallback engine documented)\n- [ ] All output files exist: `ls -lh output.*`\n- [ ] File types verified: `file output.*`\n- [ ] Content validated (spot-check with `read_file` if applicable)\n\n## When to Use shell_agent Instead\n\nAfter successfully completing this manual workflow:\n- For simple DOCX-only tasks (no PDF needed)\n- When toolchain is verified working\n- For repetitive tasks with known-good content\n\n**For documents with Unicode content requiring PDF, always use this manual workflow.**\n\n## Related Skills\n\n- `spreadsheet-direct-python`: For Excel\u002FCSV generation with Python\n- `pdf-verification-cli`: For verifying PDF page count and content after creation\n","# Document Generation with Diagnostic Workflow (Unicode-Safe)\n\n## When to Use\n\nUse this skill when document generation tasks fail or return unclear errors, especially when:\n- Generating documents in multiple formats (`.docx`, `.pdf`, `.html`)\n- **PDF generation fails with encoding\u002FLaTeX errors**\n- `shell_agent` returns \"unknown error\" without diagnostics\n- Documents contain special characters, symbols, or non-ASCII text\n- You need systematic error diagnosis rather than blind retries\n\n## ⚠️ Critical: Why This Skill Exists\n\nRecent executions show **43% effectiveness** because agents:\n- Skip unicode sanitization before PDF conversion\n- Don't try `xelatex` engine (better Unicode support)\n- Don't capture stderr for proper diagnosis\n- Exhaust iterations on repeated failures without systematic troubleshooting\n\n**This skill fixes those gaps with mandatory steps.**\n\n## Pre-Flight Validation (NEW - Required Step 0)\n\nBefore starting document generation, verify your toolchain:\n\n```\nrun_shell\ncommand: which pandoc && pandoc --version | head -3\n```\n\n```\nrun_shell\ncommand: which pdflatex xelatex wkhtmltopdf 2>\u002Fdev\u002Fnull || echo \"Some engines missing\"\n```\n\n```\nrun_shell\ncommand: python3 -c \"import sys; print(sys.version)\"\n```\n\nIf pandoc is missing, install it:\n```\nrun_shell\ncommand: apt-get update && apt-get install -y pandoc\n```\n\nFor PDF support, install LaTeX engines:\n```\nrun_shell\ncommand: apt-get install -y texlive-latex-recommended texlive-fonts-recommended texlive-xetex\n```\n\n## Core Technique\n\n**Manually split the workflow into observable, diagnostic steps:**\n1. **Pre-flight** → Verify toolchain availability\n2. **Content creation** → Use `write_file` for markdown source (visible content)\n3. **Unicode sanitization** → **MANDATORY for PDF**: Create sanitized version\n4. **Format conversion with fallback** → Try engines in order, capture stderr\n5. **Verification** → Check outputs exist and validate content\n\n## Unicode & LaTeX Compatibility (MANDATORY for PDF)\n\n**PDF generation via LaTeX has limited Unicode support.** Before PDF conversion, you MUST sanitize:\n\n| Character | Issue | Safe Replacement |\n|-----------|-------|------------------|\n| `—` (em dash) | LaTeX incompatibility | `--` |\n| `–` (en dash) | LaTeX incompatibility | `-` |\n| `\" \"` (curly quotes) | Encoding errors | `\" \"` (straight) |\n| `' '` (curly apostrophe) | Encoding errors | `'` (straight) |\n| `…` (ellipsis) | May not render | `...` |\n| `→` `←` `↑` `↓` (arrows) | LaTeX incompatibility | `->` `\u003C-` `^` `v` |\n| `✓` `✗` (checkmarks) | May not render | `[x]` `[ ]` |\n| `★` `●` (symbols) | May not render | `*` `-` |\n| `©` `®` `™` | Require packages | `(c)` `(r)` `(tm)` |\n| Non-ASCII (é, ñ, ü) | Font-dependent | Keep for xelatex, sanitize for pdflatex |\n\n**DOCX and HTML handle Unicode natively** - use original markdown for these formats.\n\n## Step-by-Step Workflow\n\n### Step 0: Pre-Flight Validation\n\n```\nrun_shell\ncommand: which pandoc || (apt-get update && apt-get install -y pandoc)\n```\n\n```\nrun_shell\ncommand: which xelatex || echo \"xelatex not available - will use fallback\"\n```\n\n### Step 1: Create Source Content with write_file\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Your content here with full Unicode support...\n  \n  ## Section 2\n  Special chars: \"quotes\" — dashes … ellipsis ✓ checkmarks\n```\n\n### Step 2: Create Sanitized Version for PDF (**MANDATORY**)\n\n**Option A: Manual sanitization with write_file**\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source_sanitized.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Your content here...\n  \n  ## Section 2\n  Special chars: \"quotes\" -- dashes ... ellipsis [x] checkmarks\n```\n\n**Option B: Automated sanitization script**\n\nFirst create the script:\n```\nwrite_file\npath: \u002Ftmp\u002Fsanitize_for_pdf.sh\ncontent: |\n  #!\u002Fbin\u002Fbash\n  INPUT=\"$1\"\n  OUTPUT=\"${2:-${1%.md}_sanitized.md}\"\n  sed -e 's\u002F—\u002F--\u002Fg' -e 's\u002F–\u002F-\u002Fg' \\\n      -e 's\u002F\"([^\"]*)\"\u002F\"\\1\"\u002Fg' -e \"s\u002F'([^']*)'\u002F\\`\\1\\`\u002Fg\" \\\n      -e 's\u002F…\u002F...\u002Fg' -e 's\u002F→\u002F->\u002Fg' -e 's\u002F←\u002F\u003C-\u002Fg' \\\n      -e 's\u002F✓\u002F[x]\u002Fg' -e 's\u002F✗\u002F[ ]\u002Fg' \\\n      -e 's\u002F©\u002F(c)\u002Fg' -e 's\u002F®\u002F(r)\u002Fg' -e 's\u002F™\u002F(tm)\u002Fg' \\\n      \"$INPUT\" > \"$OUTPUT\"\n  echo \"Sanitized: $INPUT -> $OUTPUT\"\n```\n\n```\nrun_shell\ncommand: chmod +x \u002Ftmp\u002Fsanitize_for_pdf.sh && \u002Ftmp\u002Fsanitize_for_pdf.sh \u002Ftmp\u002Fdocument_source.md \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n### Step 3: Convert to DOCX (from original, supports Unicode)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.docx 2>&1\n```\n\n**Capture stderr** with `2>&1` to see actual errors (not \"unknown error\").\n\n### Step 4: Convert to PDF with Engine Fallback Chain (**CRITICAL**)\n\n**Try engines in order: xelatex (best Unicode) → pdflatex → wkhtmltopdf**\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=xelatex 2>&1\n```\n\nIf xelatex fails, try pdflatex:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=pdflatex 2>&1\n```\n\nIf pdflatex fails, try wkhtmltopdf:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf --pdf-engine=wkhtmltopdf 2>&1\n```\n\n**If ALL engines fail**, diagnose with:\n```\nrun_shell\ncommand: file \u002Ftmp\u002Fdocument_source_sanitized.md && head -20 \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n### Step 5: Convert to HTML (from original)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.html 2>&1\n```\n\n### Step 6: Verify All Outputs\n\n```\nrun_shell\ncommand: ls -lh output.* && file output.*\n```\n\n```\nrun_shell\ncommand: [ -f output.pdf ] && echo \"PDF created: $(wc -c \u003C output.pdf) bytes\" || echo \"PDF MISSING\"\n```\n\n## Complete Example\n\n```markdown\n# Generate Client Report in Multiple Formats\n\n## Step 0: Pre-flight\nrun_shell\ncommand: which pandoc xelatex || echo \"Checking toolchain...\"\n\n## Step 1: Write markdown source\nwrite_file\npath: \u002Ftmp\u002Fclient_report.md\ncontent: |\n  # Client Investment Report\n  \n  ## Executive Summary\n  Portfolio performance shows strong returns — up 15% this quarter...\n  \n  ## Risk Analysis\n  Key metrics: \"Sharpe ratio\" ✓ passed … continuing analysis\n\n## Step 2: Sanitize for PDF (MANDATORY)\nwrite_file\npath: \u002Ftmp\u002Fclient_report_sanitized.md\ncontent: |\n  # Client Investment Report\n  \n  ## Executive Summary\n  Portfolio performance shows strong returns -- up 15% this quarter...\n  \n  ## Risk Analysis\n  Key metrics: \"Sharpe ratio\" [x] passed ... continuing analysis\n\n## Step 3: Convert to DOCX (original unicode OK)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report.md -o client_report.docx 2>&1\n\n## Step 4: Convert to PDF (sanitized, xelatex first)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report_sanitized.md -o client_report.pdf --pdf-engine=xelatex 2>&1\n\n## Step 5: Convert to HTML (original unicode OK)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fclient_report.md -o client_report.html 2>&1\n\n## Step 6: Verify\nrun_shell\ncommand: ls -lh client_report.* && file client_report.*\n```\n\n## Error Diagnosis Decision Tree\n\nWhen a conversion fails, **capture stderr** (`2>&1`) and diagnose:\n\n```\nIf error contains \"xelatex not found\" or \"LaTeX error\":\n  → Try next engine: --pdf-engine=pdflatex or --pdf-engine=wkhtmltopdf\n\nIf error contains \"encoding\" or \"UTF-8\":\n  → Unicode not properly sanitized; re-check Step 2\n  → Add -f markdown+utf8 to pandoc command\n\nIf error contains \"template\" or \"class\":\n  → LaTeX template issue; try --pdf-engine=wkhtmltopdf\n\nIf error is \"unknown error\" (no stderr captured):\n  → Re-run with 2>&1 to capture actual error message\n  → Check if pandoc is installed: which pandoc\n\nIf wkhtmltopdf fails:\n  → Install: apt-get install wkhtmltopdf\n  → Or use Python alternative: reportlab or fpdf2\n```\n\n## Alternative: Python PDF Generation (When pandoc Fails)\n\nIf all pandoc engines fail, use Python libraries directly:\n\n**Using fpdf2:**\n```\nrun_shell\ncommand: python3 -c \"\nfrom fpdf import FPDF\npdf = FPDF()\npdf.add_page()\npdf.set_font('Arial', '', 12)\npdf.cell(0, 10, 'Document Title')\npdf.output('output.pdf')\n\"\n```\n\n**Using reportlab:**\n```\nrun_shell\ncommand: python3 -c \"\nfrom reportlab.lib.pagesizes import letter\nfrom reportlab.pdfgen import canvas\nc = canvas.Canvas('output.pdf', pagesize=letter)\nc.drawString(100, 750, 'Document Title')\nc.save()\n\"\n```\n\n## Common pandoc Commands Reference\n\n```bash\n# Markdown to Word (Unicode-safe)\npandoc input.md -o output.docx\n\n# Markdown to PDF with xelatex (BEST for Unicode)\npandoc input.md -o output.pdf --pdf-engine=xelatex\n\n# Markdown to PDF with pdflatex (requires sanitization)\npandoc input.md -o output.pdf --pdf-engine=pdflatex\n\n# Markdown to PDF with wkhtmltopdf (HTML-based, good fallback)\npandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf\n\n# Markdown to HTML\npandoc input.md -o output.html\n\n# With metadata\npandoc input.md -o output.pdf --metadata title=\"Document Title\"\n\n# Force UTF-8 encoding\npandoc -f markdown+utf8 input.md -o output.pdf\n```\n\n## Troubleshooting Quick Reference\n\n| Symptom | Likely Cause | Solution |\n|---------|--------------|----------|\n| \"xelatex not found\" | Missing LaTeX engine | `apt-get install texlive-xetex` or try `--pdf-engine=wkhtmltopdf` |\n| \"LaTeX error: encoding\" | Unicode in source | Use sanitized markdown for PDF |\n| \"unknown error\" (pandoc) | stderr not captured | Re-run with `2>&1` to see real error |\n| PDF missing after conversion | All engines failed | Try Python (fpdf2\u002Freportlab) as fallback |\n| DOCX has garbled text | Encoding issue | Add `-f markdown+utf8` to pandoc command |\n| HTML renders but PDF fails | LaTeX-specific issue | wkhtmltopdf engine usually works |\n\n## Verification Checklist\n\nBefore marking task complete, verify:\n\n- [ ] Pre-flight: pandoc installed and accessible\n- [ ] Source markdown created with `write_file`\n- [ ] Sanitized version created for PDF conversion\n- [ ] DOCX generated from original (unicode preserved)\n- [ ] PDF generated with xelatex (or fallback engine documented)\n- [ ] All output files exist: `ls -lh output.*`\n- [ ] File types verified: `file output.*`\n- [ ] Content validated (spot-check with `read_file` if applicable)\n\n## When to Use shell_agent Instead\n\nAfter successfully completing this manual workflow:\n- For simple DOCX-only tasks (no PDF needed)\n- When toolchain is verified working\n- For repetitive tasks with known-good content\n\n**For documents with Unicode content requiring PDF, always use this manual workflow.**\n\n## Related Skills\n\n- `spreadsheet-direct-python`: For Excel\u002FCSV generation with Python\n- `pdf-verification-cli`: For verifying PDF page count and content after creation\n",{"name":5,"description":7},"main","6b84b0689ca0d9e7b1e4061188ff6b60758e0f8a","openspace\u002Flegacy\u002Fv1\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced-3d3a9a",944,"https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot","https:\u002F\u002Fgithub.com\u002FHKUDS","https:\u002F\u002Fsites.google.com\u002Fview\u002Fchaoh","2026-11-12 22:26:39",{"source":8,"skillName":5,"commands":57,"prompt":67,"zipAvailable":68},[58,61,64],{"tool":59,"command":60},"npx","npx skills add HKUDS\u002FAgentPilot --skill doc-gen-unicode-diagnostic",{"tool":62,"command":63},"bunx","bunx skills add HKUDS\u002FAgentPilot --skill doc-gen-unicode-diagnostic",{"tool":65,"command":66},"pnpm","pnpm dlx skills add HKUDS\u002FAgentPilot --skill doc-gen-unicode-diagnostic","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced-3d3a9a\u002FSKILL.md",true,[70],{"path":71,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":74,"sourceHtmlUrl":75},".skill_id","OTHER","其他",60,"https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced-3d3a9a\u002F.skill_id",[77,96,115,136,160,183],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":43},"01M6HYB297NDABRERJRVG0K8R0","agentpilot","Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fplugins\u002Fagentpilot\u002Fskills\u002Fagentpilot\u002FSKILL.md",[],[79,84,85,41,86,87,88,89,90,91,92,93,94,95],"prepare","requests","missing","installation","rsi","up","use","user","work","SET","run","experiments",{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":43},"01M6HYAYWXTTE1J7DJM0MFNQ4H","remember","Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fskills\u002Fremember\u002FSKILL.md",[],[98,103,104,105,106,107,108,109,110,111,112,113,114],"memory","review","auto","openspace","changes","facts","detect","entries","local","conflicts","stale","duplicates",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":122,"publishedAt":43},"01M6HYAVMPM4SBDV60R2B5HPV8","skill-discovery","Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fhost_skills\u002Fskill-discovery\u002FSKILL.md",[121],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[123,124,125,106,126,127,128,129,130,131,132,133,134,135],"skill discovery","discovery","reusable","step by step","tokens","packages","help","cloud","reliability","capabilities","browse","search","Tools",{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":143,"publishedAt":43},"01M6HYAR811B3RB0M50RBEDGN6","delegate-task","Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Fopenspace\u002Fhost_skills\u002Fdelegate-task\u002FSKILL.md",[142],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[144,145,146,106,147,148,149,150,151,125,105,90,152,153,154,155,156,157,158,159],"delegate","task","delegate task","time","improve","desktop automation","worker","community","autonomous","tool","stack","for","share","tasks","automation","MCP",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":166,"publishedAt":43},"01M6HYAM9FSGV6E52AYENDQXYH","write-special-chars-ts-check","Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fwrite-special-chars-ts-check\u002FSKILL.md",[],[167,168,169,170,171,172,173,174,175,176,177,178,179,180,155,181,182],"write special chars ts check","write","check","type","files","filters","only","template","file","python","typescript","output","Existing","type-checking","errors","script",{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":189,"publishedAt":43},"01M6HYAH05HGV7SVWSVR8PJRQD","write-special-chars-readback","Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of \u002Ftmp helper scripts.","https:\u002F\u002Fgithub.com\u002FHKUDS\u002FAgentPilot\u002Fblob\u002Fmain\u002Fopenspace\u002Flegacy\u002Fv1\u002Fshowcase\u002Fskills\u002Fwrite-special-chars-readback\u002FSKILL.md",[],[190,191,168,41,155,182,192,193,194,195,196,174,175,197,198,176],"write special chars readback","readback","helper","post","via","scripts","read","verification","cleanup"]