AGENT SKILL

document-gen-fallback

Fallback workflow for multi-format document generation when shell_agent encounters errors

License 许可
MIT
最近更新
2026-04-06
Stars
★ 0
Forks
0

01 前言 Front Matter

name
document-gen-fallback
description
Fallback workflow for multi-format document generation when shell_agent encounters errors

02 资源文件 1

03 SKILL.md 正文

Document Generation Fallback Workflow

When to Use

Use this skill when shell_agent returns unknown or unclear errors on complex document generation tasks, especially when:

  • Generating documents in multiple formats (e.g., .docx, .pdf, .html)
  • The error message doesn't provide clear debugging information
  • You need better visibility into each step of the generation process

Core Technique

Instead of delegating the entire document generation to shell_agent, manually split the workflow into discrete, observable steps:

  1. Content creation → Use write_file to create source document (Markdown)
  2. Format conversion → Use run_shell with pandoc for each target format
  3. Verification → Check output files exist and are valid

Step-by-Step Workflow

Step 1: Create Source Content with write_file

Write your document content as Markdown to a temporary source file. This gives you full visibility into the content being generated.

write_file
path: /tmp/document_source.md
content: |
  # Document Title
  
  ## Section 1
  Content here...
  
  ## Section 2
  More content...

Step 2: Convert to Target Formats with run_shell

Use run_shell with explicit pandoc commands for each format. This isolates conversion errors.

run_shell
command: pandoc /tmp/document_source.md -o output.docx
run_shell
command: pandoc /tmp/document_source.md -o output.pdf

Step 3: Verify Outputs

Check that files were created successfully:

run_shell
command: ls -lh output.docx output.pdf

Complete Example

# Generate Negotiation Strategy Document

## Step 1: Write Markdown source
write_file
path: /tmp/negotiation_strategy.md
content: |
  # Negotiation Strategy
  
  ## Executive Summary
  [Content...]
  
  ## Resolution Path
  [Content...]
  
  ## BATNA Analysis
  [Content...]

## Step 2: Convert to DOCX
run_shell
command: pandoc /tmp/negotiation_strategy.md -o negotiation_strategy.docx

## Step 3: Convert to PDF
run_shell
command: pandoc /tmp/negotiation_strategy.md -o negotiation_strategy.pdf

## Step 4: Verify
run_shell
command: ls -lh negotiation_strategy.*

Advantages Over shell_agent

Aspect shell_agent Manual Workflow
Error visibility Opaque, may retry silently Each step shows explicit output
Recovery Automatic but may loop Manual intervention at specific step
Debugging Hard to isolate failure point Clear which step failed
Control Agent decides approach You control each conversion

Common pandoc Commands

# Markdown to Word
pandoc input.md -o output.docx

# Markdown to PDF (requires LaTeX or wkhtmltopdf)
pandoc input.md -o output.pdf

# Markdown to HTML
pandoc input.md -o output.html

# With custom template
pandoc input.md --template=template.html -o output.html

# With metadata
pandoc input.md -o output.pdf --metadata title="Document Title"

Troubleshooting

  • PDF generation fails: Ensure LaTeX is installed (texlive package) or use --pdf-engine=wkhtmltopdf
  • DOCX formatting issues: Add --reference-doc=template.docx for custom styles
  • Unicode/encoding errors: Add -f markdown+utf8 to pandoc command
  • Missing pandoc: Install via apt-get install pandoc or brew install pandoc

When to Return to shell_agent

After successfully completing the manual workflow once, you can attempt shell_agent again for similar tasks, now with a known-working fallback if errors recur.

04 同仓库更多 Skills