EPUB Quality Review Skill
日本語版 / Japanese
A skill for performing quality reviews of EPUB files based on the EPUB 3.3 specification. Combines pre-parsed normative requirements (MUST/SHOULD/MAY) from the W3C EPUB 3.3 Recommendation with automated validation scripts to generate validation reports with specification rationale.
Specification Sources
| Specification | URL | Status |
|---|---|---|
| EPUB 3.3 | https://www.w3.org/TR/epub-33/ | W3C Recommendation |
| EPUB Accessibility 1.1 | https://www.w3.org/TR/epub-a11y-11/ | W3C Recommendation |
| EPUB Reading Systems 3.3 | https://www.w3.org/TR/epub-rs-33/ | W3C Recommendation |
Requirements Data
This skill includes the following pre-parsed requirements data:
| File | Contents | Count |
|---|---|---|
epub33-requirements.json |
EPUB 3.3 §2–§9 all sections | 135 items |
epub-a11y-requirements.json |
EPUB Accessibility 1.1 | 31 items |
Requirement ID formats:
EPUB33-R0001throughEPUB33-R0135: EPUB 3.3 coreEPUBA11Y-R0001throughEPUBA11Y-R0031: Accessibility
Tools
Automated Validation Script
# Run basic structure validation
bash scripts/validate-epub.sh <epub-file>
# Run with specified output directory
bash scripts/validate-epub.sh <epub-file> /path/to/output
The script checks:
- ZIP structure (mimetype, compression method)
- container.xml integrity
- Package Document required metadata
- Navigation Document structure
- Content Document XML syntax
- CSS prohibited properties
- Filename and path restrictions
- Security (file: URLs, external entities)
Specification Reference Tools
- w3c-mcp: Use
search_w3c_specs,get_w3c_specto retrieve specification metadata - web_fetch: Use when the specification text needs to be consulted
- Pre-parsed data: Reference JSON files via
Read
Verification Workflow
1. Receive EPUB file
└─ Run automated validation via scripts/validate-epub.sh
2. Review automated validation results
├─ Tally PASS / FAIL / WARN counts
└─ Check for critical violations
3. Detailed analysis against requirements JSON
├─ Identify applicable requirements from epub33-requirements.json
├─ Indicate requirement ID, section, and normative level
└─ List items requiring manual review
4. Accessibility evaluation
├─ Cross-reference with epub-a11y-requirements.json
├─ Check Schema.org metadata presence
└─ Verify WCAG compliance level
5. Generate report
└─ Output validation report in Markdown format
Verification Categories
| Category | Method | Automation | Count |
|---|---|---|---|
| zip | ZIP header / unzip | ★★★ | 11 |
| container | File structure check | ★★★ | 15 |
| metadata | OPF XML parsing | ★★★ | 9 |
| manifest | OPF XML parsing | ★★★ | 7 |
| spine | OPF XML parsing | ★★★ | 7 |
| navigation | Nav Document parsing | ★★★ | 13 |
| xhtml | XML validity check | ★★☆ | 4 |
| css | CSS analysis | ★★☆ | 3 |
| fixed-layout | OPF metadata analysis | ★★☆ | 13 |
| media-overlay | SMIL analysis | ★★☆ | 19 |
| security | File scanning | ★★☆ | 3 |
| accessibility | Metadata + manual | ★☆☆ | 31 |
Report Format
Report validation results in the following format:
## EPUB 3.3 Quality Review: [filename]
### Summary
- Inspection date: YYYY-MM-DD
- MUST violations: X items
- SHOULD non-compliance: X items
- Passed items: X items
### Validation Results
#### ❌ MUST Violations
| ID | Section | Requirement | Finding |
|:---|:---|:---|:---|
| EPUB33-R0057 | §5.4.3.1 | dc:title MUST exist | dc:title is empty |
#### ⚠️ SHOULD Non-compliance
| ID | Section | Requirement | Finding |
|:---|:---|:---|:---|
#### ✅ Passed
| Category | Items Checked | Result |
|:---|:---|:---|
#### ℹ️ Accessibility
| ID | Requirement | Status |
|:---|:---|:---|
Relationship to EPUBCheck
EPUBCheck is the official EPUB validation tool. This skill does not replace EPUBCheck, but complements it as follows:
- EPUBCheck: Exhaustive mechanical verification (automatic checking of all requirements)
- This skill: Explanations with specification rationale, improvement suggestions, and accessibility-focused advice
In environments where EPUBCheck is available, running EPUBCheck first and then using this skill's specification data to explain the results is the most effective approach.
# Install and run EPUBCheck (Java required)
java -jar epubcheck.jar target.epub
# JSON output
java -jar epubcheck.jar target.epub --json result.json
Additional References
Consult the following for detailed specification references:
| File | Contents |
|---|---|
references/spec-references.md |
Specification URLs and common issues by category |
references/fixed-layout-guide.md |
§8 Fixed Layout implementation guide |
references/media-overlay-guide.md |
§9 Media Overlay implementation guide |
references/accessibility-guide.md |
EPUB Accessibility 1.1 implementation guide |
checklist.md |
Full requirements in checklist format |
Updating
When the specification is updated (e.g., EPUB 3.4):
- Retrieve the new specification URL via w3c-mcp
- Fetch the specification text via web_fetch
- Re-extract MUST/SHOULD/MAY requirements
- Update requirements.json
- Update scripts/validate-epub.sh
- Update version information in SKILL.md