How to Customize the Working Directory for book-to-skill Extractions

Set the BOOK_SKILL_WORKDIR environment variable to an absolute path before running book-to-skill, and all extraction artifacts will be written to that directory instead of the default PID-based temporary folder.

By default, the virgiliojr94/book-to-skill library writes extraction artifacts to a system temporary directory that includes the current process ID. If you need to customize the working directory for book-to-skill extractions to a persistent or specific location, the library provides a straightforward environment variable override that applies to both CLI and programmatic usage.

How the Default Working Directory Works

The default behavior is defined in book_to_skill/config.py where the default_output_dir() function generates a temporary path unique to each process:

# book_to_skill/config.py

def default_output_dir() -> Path:
    return Path(tempfile.gettempdir()) / f"book_skill_work-{os.getpid()}"

This creates a subdirectory under the system temp folder (typically /tmp or $TMPDIR) that prevents collisions between concurrent runs. However, files written here are subject to system cleanup policies, making customization essential for persistent storage or debugging workflows.

Overriding the Working Directory with BOOK_SKILL_WORKDIR

To customize the working directory, set the BOOK_SKILL_WORKDIR environment variable. The configuration module checks for this variable at import time and uses its value verbatim when present:

# book_to_skill/config.py

OUTPUT_DIR = Path(os.environ.get("BOOK_SKILL_WORKDIR") or default_output_dir())
OUTPUT_TEXT = OUTPUT_DIR / "full_text.txt"
OUTPUT_META = OUTPUT_DIR / "metadata.json"

When BOOK_SKILL_WORKDIR is set to a non-empty string, the library bypasses the default temporary directory and writes all intermediate and final files—including full_text.txt and metadata.json—directly to your specified path. Both the high-level API and the CLI entry point in book_to_skill/cli.py consume this same OUTPUT_DIR constant.

Safety Validation and Directory Preparation

Before writing any files, the library validates the custom directory through prepare_output_dir() in book_to_skill/utils.py. This function performs critical security checks that mirror the safety of temporary directories:

• Rejects symbolic links to prevent directory traversal attacks
• Verifies the path is actually a directory, not a file
• Confirms the current user owns the directory
• Enforces 0700 permissions (read/write/execute for owner only)

These validations ensure that even when you customize the working directory for book-to-skill extractions, the process maintains strict security boundaries identical to the default temporary behavior.

Practical Implementation Examples

Shell Environment Override

For one-time CLI usage, export the variable before running the command:

export BOOK_SKILL_WORKDIR=/mnt/data/book_extractions
python -m book_to_skill /path/to/document.pdf

All output files will appear under /mnt/data/book_extractions rather than in a temporary folder.

Programmatic Configuration in Python

When using book-to-skill as a library, you must set the environment variable before importing the package, since OUTPUT_DIR is evaluated at import time:

import os
from pathlib import Path

# Must set before any book_to_skill import

os.environ["BOOK_SKILL_WORKDIR"] = str(Path("/var/lib/book_skill"))

from book_to_skill import extract

result = extract("/path/to/document.epub")

# Files are written to /var/lib/book_skill/

Temporary Context Manager for Testing

For unit tests or notebooks where you need to isolate runs without modifying global state:

import os
from contextlib import contextmanager
from pathlib import Path

@contextmanager
def temporary_workdir(path: Path):
    original = os.environ.get("BOOK_SKILL_WORKDIR")
    os.environ["BOOK_SKILL_WORKDIR"] = str(path)
    try:
        yield
    finally:
        if original is None:
            os.environ.pop("BOOK_SKILL_WORKDIR", None)
        else:
            os.environ["BOOK_SKILL_WORKDIR"] = original

with temporary_workdir(Path("/tmp/test_extraction")):
    # Extraction runs here using the custom directory

    from book_to_skill import extract
    extract("/path/to/document.pdf")

This pattern temporarily customizes the working directory and automatically restores the previous environment state afterward.

Summary

• The default working directory is a PID-based temporary folder generated by default_output_dir() in book_to_skill/config.py.
• Set the BOOK_SKILL_WORKDIR environment variable to override the output location for all extraction artifacts.
• The library validates custom directories via prepare_output_dir() in book_to_skill/utils.py, rejecting unsafe paths and enforcing 0700 permissions.
• Both the CLI and library API respect this configuration when the variable is set prior to import.

Frequently Asked Questions

What environment variable controls the book-to-skill working directory?

The BOOK_SKILL_WORKDIR environment variable controls where extraction files are written. When set to an absolute path, it overrides the default temporary directory defined in default_output_dir() in book_to_skill/config.py.

How does book-to-skill validate custom working directories?

The prepare_output_dir() function in book_to_skill/utils.py validates that the directory is not a symlink, is owned by the current user, is actually a directory, and has 0700 permissions. If any check fails, the extraction aborts to prevent security vulnerabilities.

Can I change the working directory after importing book-to-skill?

No. Because OUTPUT_DIR is evaluated at import time in book_to_skill/config.py, you must set BOOK_SKILL_WORKDIR before importing any submodules from book_to_skill. Changing the environment variable after import has no effect on the active output location.

Does the book-to-skill CLI support custom working directories?

Yes. The CLI entry point in book_to_skill/cli.py imports from the same configuration module, so exporting BOOK_SKILL_WORKDIR before running python -m book_to_skill applies the custom directory to command-line extractions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}