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

> Learn how to configure the book-to-skill work directory by setting the BOOK_SKILL_WORKDIR environment variable. Customize your project's workflow and avoid default temporary directories.

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

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py):

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) (lines 27-28):

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

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

```dotenv

# .env

BOOK_SKILL_WORKDIR=/var/tmp/book_skill_work

```

Then run normally—the variable is picked up automatically:

```bash
python -m book_to_skill <input-file>

```

### Programmatic (Script-Level)

Override within Python before invoking the extractor:

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

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) based on the resolved `OUTPUT_DIR`.

## Key Source Files

| File | Purpose |
|------|---------|
| [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py) | Entry point that relies on config for path resolution |
| [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](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). 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.