How to Override the Default Work Directory for the Book‑to‑Skill Extractor

Set the BOOK_SKILL_WORKDIR environment variable to any writable path before invoking the extractor to override the default temporary directory location.

The Book‑to‑Skill extractor generates intermediate files during document processing, storing them in a dedicated work directory. By default, this location is automatically generated under the system temporary folder using the current process ID. Understanding how to override the default work directory for the extractor allows you to integrate the tool with custom pipelines, persist outputs to specific locations, or manage disk space in constrained environments.

Understanding the Default Work Directory Behavior

The extractor defines its default output location in book_to_skill/config.py through the default_output_dir() function:

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

This implementation creates a unique subdirectory under the system temporary directory, appending the process ID to prevent collisions between concurrent runs. The extractor uses this path to store full_text.txt and metadata.json files during the extraction pipeline.

Overriding the Work Directory with BOOK_SKILL_WORKDIR

According to the source code in book_to_skill/config.py, the extractor checks for the BOOK_SKILL_WORKDIR environment variable before falling back to the default temporary location:

OUTPUT_DIR = Path(os.environ.get("BOOK_SKILL_WORKDIR") or default_output_dir())

When BOOK_SKILL_WORKDIR is set to a valid path, the OUTPUT_DIR variable uses that exact location instead of the auto-generated temporary directory. This configuration is read at import time, meaning the variable must be set before the book_to_skill module loads.

Practical Implementation Methods

You can override the work directory through several approaches depending on your execution context.

Shell Environment Export

For persistent sessions where you run multiple extractions, export the variable before invoking the CLI:

export BOOK_SKILL_WORKDIR=/tmp/my_book_skill_work
python -m book_to_skill extract path/to/document.pdf

The extractor will create and write files to /tmp/my_book_skill_work/ instead of the system temp folder.

One-Off Command Execution

For single invocations without polluting your shell environment, prefix the command:

BOOK_SKILL_WORKDIR=/var/tmp/run1 python -m book_to_skill extract book.pdf

This approach is ideal for CI/CD pipelines or scripted batch processing where each job requires an isolated work directory.

Programmatic Override in Python

When embedding the extractor within a larger Python application, set the environment variable before importing or reloading the module:

import os
from book_to_skill import cli

os.environ["BOOK_SKILL_WORKDIR"] = "/home/user/custom_workdir"
cli.main(["extract", "my_book.epub"])

Note that because config.py evaluates OUTPUT_DIR at import time, you must set the variable before any book_to_skill submodules import the configuration.

Verifying the Active Work Directory

The extractor confirms the resolved work directory at runtime. In book_to_skill/utils.py, the extract_multi_source function prints the final paths upon completion:

Workdir -> /tmp/my_book_skill_work
Text    -> /tmp/my_book_skill_work/full_text.txt
Meta    -> /tmp/my_book_skill_work/metadata.json

Check this output to verify that your BOOK_SKILL_WORKDIR override has taken effect.

Summary

• The default work directory is auto-generated in the system temp folder using the process ID, defined in book_to_skill/config.py.
• Set the BOOK_SKILL_WORKDIR environment variable to override the default location with any writable directory path.
• The configuration module evaluates the environment variable at import time via os.environ.get("BOOK_SKILL_WORKDIR").
• Override methods include shell exports, inline command variables, or programmatic os.environ assignment before module import.
• Verify the active directory by examining the runtime output from book_to_skill/utils.py.

Frequently Asked Questions

What environment variable controls the work directory?

The BOOK_SKILL_WORKDIR environment variable controls the extractor's work directory. When set, the value overrides the default temporary directory generated by default_output_dir() in book_to_skill/config.py. The variable is read once at module initialization.

Does the custom directory need to exist before running the extractor?

The custom directory must exist or be creatable by the running process. The extractor attempts to write full_text.txt and metadata.json to the specified path immediately upon execution. Ensure the directory has appropriate write permissions to avoid runtime errors.

How can I confirm which work directory is being used?

The extractor prints the resolved work directory at the end of the extraction process in book_to_skill/utils.py. Look for output lines beginning with Workdir -> followed by the absolute path to verify your override is active.

Will overriding the work directory affect other configuration settings?

No, overriding the work directory only changes the OUTPUT_DIR path variable. Other configuration settings in book_to_skill/config.py, such as OUTPUT_TEXT and OUTPUT_META (which define the filenames within the work directory), remain unaffected by the BOOK_SKILL_WORKDIR environment variable.

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