How to Configure the Work Directory for book-to-skill

Set the BOOK_SKILL_WORKDIR environment variable to override the default PID-scoped temporary directory.

By default, book-to-skill creates a temporary working directory for each run under the system temp folder, scoped to the process PID. Understanding how to configure this work directory is essential for debugging, CI pipelines, or any scenario where you need stable, predictable file locations.

Default Work Directory Behavior

The book-to-skill tool generates extraction artifacts—specifically a full-text file and metadata JSON—in a dedicated working directory. Without configuration, this directory is created automatically using the default_output_dir() function in book_to_skill/config.py:

def default_output_dir() -> Path:
    # Creates a path like /tmp/book_skill_work-<pid>

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

This default ensures isolation: each process gets its own directory based on its PID, preventing collisions between concurrent runs. The directory is created with mode 0700 to restrict access to the owner.

Overriding with BOOK_SKILL_WORKDIR

To specify a custom location, set the BOOK_SKILL_WORKDIR environment variable. The configuration is read at module load time in book_to_skill/config.py (lines 27-28):

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

When BOOK_SKILL_WORKDIR is set to a non-empty path, book-to-skill uses it exactly as provided. When unset or empty, the fallback default_output_dir() applies.

Behavior Matrix

Situation	Resulting Work Directory
Variable unset	default_output_dir() — PID-scoped temp directory
Variable set to non-empty path	Specified path used directly (shared across runs)
Variable set to empty string	Falls back to default_output_dir()
Insufficient permissions	Failure unless directory is writable by process

Configuration Methods

Shell-Level (One-Off)

Set the variable for a single invocation without persisting it:

BOOK_SKILL_WORKDIR=/tmp/my_book_skill_work \
python -m book_to_skill <input-file>

Dotenv File (Project-Level)

Create a .env file in your project root for tools that load environment variables:

# .env

BOOK_SKILL_WORKDIR=/var/tmp/book_skill_work

Then run normally—the variable is picked up automatically:

python -m book_to_skill <input-file>

Programmatic (Script-Level)

Override within Python before invoking the extractor:

import os
from book_to_skill.utils import main as book_to_skill_main

# Set custom directory

os.environ["BOOK_SKILL_WORKDIR"] = "/home/user/book_skill_work"

# Execute extraction

book_to_skill_main()

Set the environment variable before importing book_to_skill.config if you need the override to take effect at import time.

Inspecting Runtime Paths

To verify the actual paths being used, import the configuration module directly:

from book_to_skill import config

print("Working directory :", config.OUTPUT_DIR)
print("Full-text file   :", config.OUTPUT_TEXT)
print("Metadata file    :", config.OUTPUT_META)

Typical output:

Working directory : /tmp/book_skill_work-12345
Full-text file   : /tmp/book_skill_work-12345/full_text.txt
Metadata file    : /tmp/book_skill_work-12345/metadata.json

These paths are constructed in book_to_skill/config.py based on the resolved OUTPUT_DIR.

Key Source Files

File	Purpose
book_to_skill/config.py	Defines default_output_dir(), reads BOOK_SKILL_WORKDIR, exposes OUTPUT_DIR, OUTPUT_TEXT, OUTPUT_META
book_to_skill/cli.py	Entry point that relies on config for path resolution
scripts/extract.py	User-facing CLI script that ultimately respects the work-directory setting

Summary

• Default: PID-scoped temp directory created under tempfile.gettempdir()
• Override: Set BOOK_SKILL_WORKDIR environment variable
• Security: Directories created with 0700 permissions
• Concurrency risk: Shared directories when using custom paths may cause file collisions

Frequently Asked Questions

What happens if BOOK_SKILL_WORKDIR points to a non-existent directory?

book-to-skill will fail when attempting to write files unless the directory is created beforehand. Ensure the path exists and is writable by the process before running.

Can multiple runs use the same work directory?

Yes, but with caution. When BOOK_SKILL_WORKDIR is set to a fixed path, concurrent runs will write to the same location, potentially overwriting full_text.txt and metadata.json. Use PID-scoped defaults for isolation or implement external coordination for shared directories.

Why does the default include the process PID?

The PID suffix prevents collisions when multiple book-to-skill processes run simultaneously on the same machine. Each process receives a unique directory, eliminating race conditions on output files.

How do I debug path issues?

Import book_to_skill.config and inspect OUTPUT_DIR, OUTPUT_TEXT, and OUTPUT_META at runtime. This reveals the resolved paths regardless of whether they came from the environment variable or the default generator.

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