# Understanding the Update / Fold-in Workflow for Maintaining Agent Skills

> Master the Update Fold-in workflow to efficiently maintain agent skills. Learn how this incremental merge process preserves version history and updates chapter files without full regeneration.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: best-practices
- Published: 2026-08-24

---

**The Update / Fold-in workflow is an incremental merge process that adds new source material to an existing skill directory without regenerating the entire structure, preserving version history while updating chapter files, glossaries, and indices.**

The `book-to-skill` project by virgiliojr94 provides a deterministic pipeline for converting technical books into structured agent skills. When you need to incorporate new chapters, revised content, or additional source documents into an established skill, the **Update / Fold-in workflow** provides a non-destructive merge mechanism that maintains your skill's integrity and existing repository history.

## How the Update / Fold-in Workflow Operates

### Triggering the Workflow (Mode 4)

According to [`docs/usage.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/usage.md), the workflow activates when you invoke the CLI with a source file and an existing skill folder as the second argument. This pattern signals **Mode 4** operation, causing the tool to bypass full conversion steps and jump directly to the merge logic.

```bash

# Add new material to an existing skill

book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

```

When the tool detects that `~/.claude/skills/project-knowledge` already contains a [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file, it automatically initiates the six-phase Update / Fold-in process instead of creating a new skill from scratch.

### Phase 1: Reading the Existing Skill Structure

The workflow begins by parsing the current skill metadata, chapter index, and topic index from [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md). The system scans the `chapters/` directory to identify the highest existing chapter number, establishing the baseline for appending new content.

### Phase 2: Content Matching and Classification

The workflow inspects the newly extracted text stored in [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) (produced by [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)) to determine whether content represents an **update** to existing chapters or a **brand-new addition**. This classification dictates whether files are modified in place or appended after the current maximum chapter number using sequential naming (e.g., `ch13-*.md`).

### Phase 3: Chapter Summary Generation

For each new or revised chapter, the system generates concise summaries following the formatting rules defined in Step 7 of the generation pipeline. These summaries are written to or overwritten in the `chapters/` directory, ensuring the index remains synchronized with content changes.

### Phase 4: Merging Supporting Files

The workflow performs intelligent merges on auxiliary content files:

- **Glossary entries** are alphabetized, with new terms appended and duplicates receiving additional chapter references
- **Pattern definitions** are consolidated, preserving existing entries while incorporating new discoveries
- **Cheatsheet entries** are updated with expanded coverage

This phase rewrites [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md), [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md), and [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md) with consolidated, de-duplicated content.

### Phase 5: Master Index Regeneration

The system updates the master [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file to reflect revised metadata, including updated chapter counts, page counts, and source lists. The master index and topic index are refreshed to incorporate cross-references to the new material.

### Phase 6: Validation and Reporting

The final phase executes validation scans, offers optional git commit and push operations, and prints a summary report detailing added chapters, updated files, and merged glossary terms. This concludes the atomic update transaction.

## Architectural Foundations

The Update / Fold-in workflow relies on several design principles implemented in the `book-to-skill` architecture according to [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md):

**Deterministic extraction** ensures that [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) produces consistent [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) output for identical inputs. The workflow consumes this extracted text without re-processing previously ingested files, keeping the pipeline fast and reproducible.

**Modular skill layout** enforces self-contained directory structures ([`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) + `chapters/` + supporting files). This modularity enables safe in-place merges, facilitates git-based versioning, and supports distribution via package managers.

**Idempotent merge operations** allow the workflow to run repeatedly without side effects. Duplicate glossary terms are automatically de-duplicated with aggregated chapter references, ensuring repeated runs produce identical outputs.

## Practical Implementation Examples

### CLI Invocation for Incremental Updates

```bash

# Merge new research paper into existing skill

book-to-skill ~/downloads/microservices-patterns.pdf ~/.claude/skills/distributed-systems

```

### Programmatic Python Integration

```python
import subprocess
import os

skill_dir = os.path.expanduser("~/.claude/skills/distributed-systems")
new_source = os.path.expanduser("~/downloads/microservices-patterns.pdf")

# Trigger Update / Fold-in via subprocess

subprocess.run([
    "book-to-skill",
    new_source,
    skill_dir
], check=True)

```

### Resulting Glossary Merge

After processing, your [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md) might contain merged entries like:

```markdown

## Glossary

- **CAP Theorem** — Consistency, Availability, Partition tolerance (Ch 04, Ch 13)
- **Event Sourcing** — Store state as a sequence of immutable events (Ch 07)
- **Saga Pattern** — Manage long-running transactions via compensating operations (Ch 13)

```

The *CAP Theorem* entry shows aggregated references from both existing Chapter 4 and newly added Chapter 13, while *Saga Pattern* represents entirely new content from the latest source document.

## Summary

- The **Update / Fold-in workflow** enables incremental skill maintenance without requiring full regeneration
- **Six distinct phases** ensure comprehensive updates to indices, chapters, and supporting files while preserving existing structure
- **Deterministic extraction** via [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) guarantees reproducible results across repeated runs
- **Idempotent merge logic** safely handles duplicate content and aggregates chapter references automatically
- **Git integration** supports version-controlled skill evolution with atomic commits and push operations

## Frequently Asked Questions

### What happens if I run the Update / Fold-in workflow multiple times on the same source?

The workflow is **idempotent**. Running it repeatedly on identical source material produces the same result without creating duplicate entries. The merge logic detects existing content and only appends new chapter references or missing glossary terms, ensuring your skill remains clean regardless of how many times you execute the command.

### Does the workflow modify chapters that haven't changed in the new source?

No. During **Phase 2: Content Matching**, the system specifically identifies whether extracted content represents revisions to existing chapters or brand-new material. Unchanged chapters remain untouched on disk, preserving their timestamps and git history. Only affected chapters undergo rewriting during the summary generation phase.

### How does the tool handle version control during the update process?

When your skill directory resides in a git repository, **Phase 6** offers optional automated commit and push operations. The workflow stages all modified files—including updated [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md), new chapter files, and merged glossaries—then commits them with a descriptive message summarizing the additions. This integration maintains complete audit trails of skill evolution.

### Can I merge multiple PDFs or books into a single skill using this workflow?

Yes, though the workflow processes one source at a time per invocation. Run the CLI sequentially with different source files targeting the same skill directory. Each invocation appends new chapters incrementally. The extractor ([`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)) processes each source independently, producing separate [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) files that the Update / Fold-in workflow consumes to expand your skill's knowledge base.