The Complete Production SOP: How to Deploy and Run Kindle MOBI & AZW3 Ebook Optimizer in Autonomous AI Agents
Step-by-step SOP to install and run the Kindle MOBI & AZW3 Optimizer in Codex, Claude Code, and Cursor. Convert EPUB to AZW3 with Calibre CLI.
Technical Overview & Architectural Context
Autonomous coding agents frequently stumble when converting digital documents like EPUB and Markdown into Kindle-ready formats (AZW3, MOBI, and KFX). Left to default behaviors, LLMs often attempt naive file renaming, emit non-standard CSS stylesheets that collapse on E-ink screens, or fail to inject necessary metadata and cover artifacts into Kindle container files. Furthermore, agents often omit Calibre's device-specific output profiles, leading to improper pagination, oversized margins, broken font metrics, and invisible book covers in the Kindle Home grid. The Kindle MOBI & AZW3 Ebook Optimizer skill establishes a rigorous deterministic boundary around Calibre's `ebook-convert` utility. By constraining agent operations to verified CLI flags—such as `--output-profile=kindle_paperwhite`, explicit cover injection via `--cover`, and typography normalizations with `--extra-css`—the skill guarantees consistent, high-fidelity rendering on E-ink hardware while safeguarding local file system boundaries.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent's global or project-level skill registry.
Agent runtimes such as Claude Code and Cursor scan defined directories (`.agents/skills` or `.cursor/rules`) for YAML frontmatter definitions. Placing the skill in the workspace enables dynamic trigger detection when working with EPUB, MOBI, and AZW3 conversion pipelines.
mkdir -p .agents/skills/mobi-azw3-kindle-converter && curl -fsSL https://askills.dev/api/skills/mobi-azw3-kindle-converter/raw -o .agents/skills/mobi-azw3-kindle-converter/SKILL.md---
name: "mobi-azw3-kindle-converter"
description: "Optimize and convert digital publications for Amazon Kindle devices using Calibre CLI."
metadata:
author: "Kovid Goyal"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "convert epub to azw3 calibre"
- "optimize ebook for kindle"
- "embed cover image in mobi"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: true
net_access: false
---
# Kindle MOBI & AZW3 Ebook Optimizer
Converts EPUB and Markdown files into Amazon Kindle formats (AZW3, KFX, MOBI) using Calibre ebook-convert.Place the skill in `.agents/skills` at the repository root rather than global user directories to ensure consistent conversion rules across CI/CD and multi-agent teams.
Ensure `shell_exec` permission is enabled in your runtime security policy if the agent needs to invoke `ebook-convert` directly within the workspace sandbox.
Calibre CLI Dependency Verification & Sandbox Configuration
Verify Calibre binaries and configure output paths within the workspace boundary.
The skill requires the `ebook-convert` binary provided by Calibre. In containerized or Linux development environments, agents must verify that headless dependencies (like Qt and libgl1) are present so Calibre can render book components without launching an X11 server.
which ebook-convert || sudo apt-get update && sudo apt-get install -y calibre#!/usr/bin/env bash
set -euo pipefail
if ! command -v ebook-convert &> /dev/null; then
echo "ERROR: Calibre CLI (ebook-convert) not found in system PATH." >&2
exit 1
fi
ebook-convert --version
echo "Calibre CLI is verified and ready for conversion SOPs."On macOS systems with GUI Calibre installed, symlink `/Applications/calibre.app/Contents/MacOS/ebook-convert` into `/usr/local/bin` to expose the CLI to Cursor and Claude Code.
Avoid running conversions directly on root-mounted drives; keep inputs and outputs strictly under the active workspace path to comply with sandbox rules.
Intent Matching & Trigger Invocation
Trigger automated Kindle conversion workflows using natural language prompts.
When prompted with registered triggers such as 'convert epub to azw3 calibre', the agent matches the skill frontmatter and constructs the deterministic `ebook-convert` command using Kindle Paperwhite profiles, typographic indentation, and cover embedding.
ebook-convert ./dist/book.epub ./dist/book.azw3 --output-profile=kindle_paperwhite --cover=./assets/cover.jpg --extra-css="p { text-indent: 1.5em; margin: 0; }"Always provide the exact paths to cover artwork and source EPUB in the prompt to prevent the agent from guessing non-existent file names.
Old MOBI formats do not support modern CSS flexbox or modern layout properties. Instruct the agent to target AZW3 or modern MOBI (`--mobi-file-type=both`) for Kindle devices.
Verification, Quality Gate & Kindle Preview Inspection
Validate AZW3 container integrity and confirm cover artifact inclusion.
After the agent executes the conversion, verify the produced file using `ebook-meta` to confirm metadata, title, author, and embedded cover image records are properly written without corruption.
ebook-meta ./dist/book.azw3#!/usr/bin/env bash
set -euo pipefail
AZW3_FILE="./dist/book.azw3"
if [ ! -f "$AZW3_FILE" ]; then
echo "Validation failed: $AZW3_FILE does not exist." >&2
exit 1
fi
echo "Validating Kindle AZW3 metadata..."
ebook-meta "$AZW3_FILE" | grep -E "(Title|Author|Cover)"
echo "Kindle compilation verified successfully."Check output file size: if an AZW3 file is smaller than expected, the cover image or embedded fonts may have failed compression or inclusion.
Kindle devices may silently reject AZW3 files larger than 650MB or books containing unclosed HTML tags inside internal XHTML chapters.
Real-World Scenario: Automated Technical Manual Compilation from EPUB to AZW3 for Kindle Paperwhite
“Please optimize our technical documentation handbook for Kindle devices. Convert 'build/manual.epub' to AZW3 using the Kindle Paperwhite profile, embed 'assets/cover.jpg' as the book cover, and enforce 1.5em paragraph indents with zero margins using the mobi-azw3-kindle-converter skill.”
Runtime Troubleshooting & Failure Modes
Root Cause: Calibre's ebook-convert relies on Qt rendering engines which fail in headless Docker containers or remote CI runners when X11 libraries are missing.
export QT_QPA_PLATFORM=offscreen && sudo apt-get install -y libgl1-mesa-glx libegl1 libxkbcommon-x11-0Root Cause: Agent executed ebook-convert from an incorrect working directory or specified a relative path not resolving from the repository root.
test -f "$(pwd)/assets/cover.jpg" && ebook-convert ./build/manual.epub ./build/manual.azw3 --cover="$(pwd)/assets/cover.jpg"Frequently Asked Questions (Kindle MOBI & AZW3 Ebook Optimizer SOP)
Q:Can I use Kindle MOBI & AZW3 Ebook Optimizer across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill adheres strictly to the universal SKILL.md specification. Once installed in `.agents/skills` or `.cursor/rules`, any compliant runtime (Codex Desktop, Claude Code, Cursor, or Windsurf) will parse the triggers and apply the Calibre conversion SOPs consistently.
Q:Why should I convert to AZW3 instead of standard MOBI for Kindle devices?
Amazon has deprecated legacy MOBI formats for modern Kindle devices and apps. AZW3 (KF8) supports modern CSS styling, embedded OpenType/TrueType fonts, Kindle media queries, and sharper typography, while preserving backward compatibility across modern E-ink hardware.
Q:Does this skill require escalated root or container permissions?
No. The skill operates with a 98/100 security score under standard workspace permissions (`fs_read: true`, `fs_write: workspace`, `net_access: false`). It only requires read access to your input assets and write access to produce the converted ebook files.
Ready to equip your autonomous agent with Kindle MOBI & AZW3 Ebook Optimizer?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.