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

> Customize book to skill extractions by setting the BOOK_SKILL_WORKDIR environment variable to an absolute path. Learn how to control your extraction artifact destination.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) where the `default_output_dir()` function generates a temporary path unique to each process:

```python

# 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:

```python

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json)—directly to your specified path. Both the high-level API and the CLI entry point in [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash
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:

```python
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:

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.