# Doc Gen Unicode Diagnostic

Systematic document generation with unicode sanitization, engine fallback chain, and...

- Repository: https://github.com/HKUDS/AgentPilot (7784 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add HKUDS/AgentPilot --skill doc-gen-unicode-diagnostic -g -a claude-code -y`
Codex: `npx skills add HKUDS/AgentPilot --skill doc-gen-unicode-diagnostic -g -a codex -y`
Cursor: `npx skills add HKUDS/AgentPilot --skill doc-gen-unicode-diagnostic -g -a cursor -y`
Gemini CLI: `npx skills add HKUDS/AgentPilot --skill doc-gen-unicode-diagnostic -g -a gemini-cli -y`

## Description

Systematic document generation with unicode sanitization, engine fallback chain, and explicit error diagnosis

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Document Generation with Diagnostic Workflow (Unicode-Safe)

## When to Use

Use this skill when document generation tasks fail or return unclear errors, especially when:
- Generating documents in multiple formats (`.docx`, `.pdf`, `.html`)
- **PDF generation fails with encoding/LaTeX errors**
- `shell_agent` returns "unknown error" without diagnostics
- Documents contain special characters, symbols, or non-ASCII text
- You need systematic error diagnosis rather than blind retries

## ⚠️ Critical: Why This Skill Exists

Recent executions show **43% effectiveness** because agents:
- Skip unicode sanitization before PDF conversion
- Don't try `xelatex` engine (better Unicode support)
- Don't capture stderr for proper diagnosis
- Exhaust iterations on repeated failures without systematic troubleshooting

**This skill fixes those gaps with mandatory steps.**

## Pre-Flight Validation (NEW - Required Step 0)

Before starting document generation, verify your toolchain:

```
run_shell
command: which pandoc && pandoc --version | head -3
```

```
run_shell
command: which pdflatex xelatex wkhtmltopdf 2>/dev/null || echo "Some engines missing"
```

```
run_shell
command: python3 -c "import sys; print(sys.version)"
```

If pandoc is missing, install it:
```
run_shell
command: apt-get update && apt-get install -y pandoc
```

For PDF support, install LaTeX engines:
```
run_shell
command: apt-get install -y texlive-latex-recommended texlive-fonts-recommended texlive-xetex
```

## Core Technique

**Manually split the workflow into observable, diagnostic steps:**
1. **Pre-flight** → Verify toolchain availability
2. **Content creation** → Use `write_file` for markdown source (visible content)
3. **Unicode sanitization** → **MANDATORY for PDF**: Create sanitized version
4. **Format conversion with fallback** → Try engines in order, capture stderr
5. **Verification** → Check outputs exist and validate content

## Unicode & LaTeX Compatibility (MANDATORY for PDF)

The rest: https://github.com/HKUDS/AgentPilot/blob/HEAD/openspace/benchmarks/gdpval/skills/document-gen-fallback-enhanced-enhanced-3d3a9a/SKILL.md