aiskillstore ASCII Preview Generate Skill
Purpose
This skill uses AI to create a meaningful ASCII text-based representation of the PDF page layout. The AI:
- Analyzes both the PDF page image and extracted text data
- Creates a structured ASCII preview showing page organization
- Represents heading hierarchy, paragraphs, lists, and tables visually
- Provides clear structural context for downstream HTML generation
The ASCII preview serves as a structured representation of page layout, enabling the downstream AI-HTML generator to understand both visual layout and content structure.
What to Do
Load input files
- Read
02_page_XX.png(visual reference) - Read
01_rich_extraction.json(text spans with metadata) - Verify all required fields present
- Read
Invoke AI to analyze and represent
- Send PNG image to Claude (visual reference)
- Include extracted text data (JSON)
- Request ASCII layout representation
- AI determines structure and relationships
AI generates ASCII preview
- AI analyzes heading hierarchy from extraction data
- AI identifies paragraphs and their relationships
- AI represents lists with proper formatting
- AI shows table layouts if present
- AI creates visual representation using ASCII characters
Validate ASCII output
- Verify output is readable text
- Check that all content elements represented
- Confirm structure is clear and logical
Save to persistent file
- Save to:
output/chapter_XX/page_artifacts/page_YY/03_page_XX_ascii.txt - Include metadata (page number, chapter, timestamp)
- Save to:
Input Parameters
rich_extraction_file: <str> - Path to 01_rich_extraction.json
page_png: <str> - Path to 02_page_XX.png (optional, for visual validation)
output_file: <str> - Path to save ASCII preview
book_page: <int> - Book page number (for display)
chapter: <int> - Chapter number (for display)
Output Format
ASCII Preview Structure
The ASCII preview uses this structure:
================================================================================
PAGE XX ASCII LAYOUT PREVIEW
================================================================================
Book Page: YY | Chapter: Z | PDF Index: XX | Dimensions: 612x792px
--------------------------------------------------------------------------------
[PAGE CONTENT WITH ASCII ART AND ANNOTATIONS]
STRUCTURE SUMMARY:
[Element counts and types]
================================================================================
Example Output
================================================================================
PAGE 16 ASCII LAYOUT PREVIEW
================================================================================
Book Page: 17 | Chapter: 2 | PDF Index: 16 | Dimensions: 612x792px
--------------------------------------------------------------------------------
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ [H1 Heading - 27pt Bold] │
│ ████████████████████████████████ │
│ █ Rights in Real Estate █ │
│ ████████████████████████████████ │
│ │
│ ───────────────────────────────────────────────────────────────── │
│ [Divider] │
│ │
│ [H2 Section Heading - 11pt Bold All-Caps] │
│ REAL PROPERTY RIGHTS │
│ │
│ [Paragraph 1 - 11pt Regular] │
│ Real property consists of physical land and the legal rights │
│ associated with ownership. These rights form what is commonly │
│ referred to as the "bundle of rights." │
│ │
│ [H4 Subsection - 11pt Bold] │
│ Physical characteristics. │
│ │
│ [Paragraph 2 - 11pt Regular] │
│ Land has unique physical characteristics that distinguish it from │
│ other types of assets. The most important characteristics include: │
│ │
│ [Bullet List - 3 items] │
│ ▶ Immobility - Land cannot be moved from one location to │
│ another. This fact has significant legal and economic │
│ implications. │
│ ▶ Indestructibility - Land is permanent and cannot be │
│ destroyed. Although structures on land can be destroyed, │
│ the land itself endures. │
│ ▶ Uniqueness - Each parcel of land is unique due to its │
│ location. "Not two parcels of land are exactly alike due to │
│ their geographic location." │
│ │
│ [H4 Subsection - 11pt Bold] │
│ Interdependence. │
│ │
│ [Paragraph 3 - 11pt Regular] │
│ All land exists in relation to other land. Therefore, the value │
│ of land is dependent on the land around it... │
│ │
└─────────────────────────────────────────────────────────────────────────┘
STRUCTURE SUMMARY:
─────────────────
Page Type: Chapter Continuation
Total Elements: 12
Headings (3):
• H1: 1 instance (27pt, bold) - "Rights in Real Estate"
• H2: 1 instance (11pt, bold, all-caps) - "REAL PROPERTY RIGHTS"
• H4: 2 instances (11pt, bold) - "Physical characteristics", "Interdependence"
Paragraphs (3):
• Body text: 3 paragraphs total
• Average paragraph length: ~45 words
• Text flow: Top to bottom, left to right
Lists (1):
• Bullet list with 3 items
• Indentation: 2em from left margin
• Separator: "▶" character
Tables: 0
Images: 0
Font Summary:
• 27pt: 1 instance (heading)
• 11pt: 7 instances (body, subsections, lists)
• Total unique fonts: 2 (Arial-Bold, Times-Regular)
Confidence Assessment:
• Heading hierarchy: 100% confident
• Element types: 95% confident
• Content flow: 90% confident
• (Lower confidence = ambiguous or unusual formatting)
================================================================================
AI Prompt Template
The prompt sent to Claude to generate ASCII preview:
You are creating an ASCII text-based layout preview of a PDF page.
VISUAL REFERENCE (PDF Page):
[PNG Image Attached]
EXTRACTED TEXT DATA:
[JSON Attached]
TASK:
Generate an ASCII text representation of this page's layout and structure.
REQUIREMENTS:
1. ASCII Format:
- Use box drawing characters for visual clarity (┌─┐│└┘)
- Show page boundaries
- Use spacing to represent actual layout
2. Element Representation:
- Headings: Show in ASCII, mark with [H1], [H2], [H3], [H4]
- Paragraphs: Show first line, indicate continuation
- Lists: Use ▶ or • characters, maintain structure
- Tables: Show column alignment and structure
- Spacing: Represent actual gaps between elements
3. Annotations:
- Label each element type [Heading], [Paragraph], [List], etc.
- Show font size context (11pt, 27pt, etc.)
- Note text styling (Bold, All-Caps, etc.)
4. Summary Statistics:
- Count headings by level (h1, h2, h3, h4)
- Count paragraphs
- Count lists and items
- Note any tables or images
5. Readability:
- Keep lines under 80 characters
- Use clear visual separation
- Make structure obvious at a glance
OUTPUT:
================================================================================ PAGE XX ASCII LAYOUT PREVIEW ================================================================================
Book Page: YY | Chapter: Z | PDF Index: XX
[ASCII representation with visual structure]
STRUCTURE SUMMARY: [Element counts and types]
VALIDATION:
- ASCII must be readable text
- All major content elements must be represented
- Structure must be clear and logical
- Total elements count must match data
AI Generation Process
Load inputs
02_page_XX.png- Visual reference01_rich_extraction.json- Text spans with metadata
Invoke Claude API
- Send image as multi-modal input
- Include extracted data in prompt
- Request ASCII layout preview
Extract and validate output
- Parse ASCII from response
- Verify readability
- Check element representation
Save to file
- Write to
output/chapter_XX/page_artifacts/page_YY/03_page_XX_ascii.txt
- Write to
Quality Checks
Before declaring ASCII preview complete:
File output
- Output file created and readable
- File is valid text (UTF-8 encoding)
- File size meaningful (> 500 bytes)
Content representation
- All major page elements represented
- Heading hierarchy shown clearly
- Paragraphs indicated and readable
- Lists properly formatted with bullets/markers
- Tables (if present) shown with alignment
Accuracy against source data
- Structure matches rich_extraction.json
- Element counts reasonable
- Text content accurate (no changes)
- Layout represents visual (PNG) appearance
Readability and format
- ASCII art is clear and clean
- Line length reasonable (< 100 chars)
- Box drawing characters render properly
- Annotations are clear and helpful
- Summary section present and accurate
Output Metadata
{
"preview_file": "03_page_16_ascii.txt",
"page": 16,
"book_page": 17,
"chapter": 2,
"generated_at": "2025-11-08T14:31:00Z",
"source_file": "01_rich_extraction.json",
"elements_detected": {
"headings": 4,
"paragraphs": 3,
"lists": 1,
"tables": 0,
"images": 0
},
"confidence_scores": {
"overall": 0.93,
"heading_hierarchy": 1.0,
"element_types": 0.95,
"content_flow": 0.90
}
}
Use in Downstream Processing
The ASCII preview is used by Skill 3 (ai-html-generate) as one of three inputs:
02_page_XX.png- Visual reference (pixel data)01_rich_extraction.json- Parsed text with metadata03_page_XX_ascii.txt- Structural representation ← This skill creates
Together, these three inputs give the AI complete context for accurate HTML generation.
Error Handling
If PNG image fails to load:
- Fall back to text-only analysis using rich_extraction.json
- AI still generates ASCII but without visual reference
- Note in metadata: "Image unavailable"
- Proceed (text data is sufficient for structure)
If rich_extraction.json is invalid:
- Use PNG image and AI visual analysis
- Attempt ASCII generation from visual alone
- Log warning about missing text data
- Proceed with AI best judgment
If AI response is not valid text:
- Validate encoding and line breaks
- Retry request if necessary
- Escalate if repeated failures
If ASCII structure seems incomplete:
- AI may have missed elements due to image quality
- Downstream HTML generation has visual reference for verification
- Quality gates will catch if output is insufficient
Success Criteria
✓ ASCII preview file created successfully ✓ File contains all page elements in structured format ✓ Heading hierarchy is clear and logical ✓ All text content included and readable ✓ Summary statistics accurate ✓ File is well-formatted and unambiguous ✓ Ready for AI HTML generation with complete context
Next Steps
Once ASCII preview is complete:
- Skill 3 (ai-html-generate) uses this + PNG + extraction for HTML
- AI has maximum context: visual (PNG) + text (extraction) + structure (ASCII)
- Result is accurate, semantically correct HTML
Troubleshooting
ASCII preview is incomplete: Check source rich_extraction.json has all text spans Heading hierarchy looks wrong: Verify font sizes in extraction data Lists not detected: Check for bullet character encoding issues Spacing is off: Ensure coordinate system matches PDF (top-left origin)
Design Notes
- This skill is AI-powered (probabilistic generation)
- Output is human-readable (for debugging and validation)
- Output is machine-parseable (for downstream processing)
- Input is multi-modal (visual image + structured text data)
- AI understands context to create meaningful layout preview
- Critical bridge between visual and textual representations
- Enables downstream HTML generation with complete context