code-example-validator

Code Example Validator Skill

Purpose

Validate code examples embedded in chapter markdown files, including syntax-only checks and opt-in execution for :runnable blocks.

Capabilities

1. Extract fenced code blocks from markdown files
2. Validate syntax per language (Python, JavaScript, Bash, etc.)
3. Execute trusted :runnable examples in a sandbox backend
4. Report validation results as JSON

Scripts

• scripts/validate_code.py — Extract and validate code blocks from a markdown file

Usage

.venv/bin/python3 .claude/skills/code-example-validator/scripts/validate_code.py <markdown_file>
.venv/bin/python3 .claude/skills/code-example-validator/scripts/validate_code.py --execute --sandbox auto output/chapters/ko/
.venv/bin/python3 .claude/skills/code-example-validator/scripts/validate_code.py --execute --sandbox process --allow-unsafe-process output/chapters/ko/

Output: JSON to stdout

{
  "file": "ch01_introduction.md",
  "total_blocks": 5,
  "valid": 4,
  "invalid": 1,
  "errors": [
    {
      "block_index": 3,
      "language": "python",
      "line_in_file": 45,
      "error": "SyntaxError: unexpected EOF while parsing"
    }
  ]
}

When to Use

• Writer Agent after completing a chapter (Step 3)
• Editor Agent during validation (Step 4)

Supported Languages

• Python: ast.parse() validation
• JavaScript: node --check if available
• Bash/Shell: bash -n syntax check
• Other languages: skip validation, report as "unchecked"

Failure Handling

• If a language validator is not available (e.g., node not installed): skip, mark as "unchecked"
• Never fail the entire validation because of one unsupported language
• --execute --sandbox auto prefers Docker isolation (--network none, read-only rootfs, tmpfs workspace)
• Process execution requires --allow-unsafe-process and is for trusted local examples only
• Runnable blocks with obvious network usage (requests, urllib, socket, http.client, curl, wget, nc, ssh) fail before execution