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

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, 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.

# 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 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. 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 (produced by 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, patterns.md, and cheatsheet.md with consolidated, de-duplicated content.

Phase 5: Master Index Regeneration

The system updates the master 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:

Deterministic extraction ensures that scripts/extract.py produces consistent 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 + 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

# Merge new research paper into existing skill

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

Programmatic Python Integration

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 might contain merged entries like:

## 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 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, 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) processes each source independently, producing separate full_text.txt files that the Update / Fold-in workflow consumes to expand your skill's knowledge base.

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