# How Data Flows Through Distilly from User Materials to Agent Hosts

> Understand data flow in Distilly: learn how user materials become validated payloads and reach agent hosts for automatic execution. Explore the Distilly repository.

- Repository: [Tianyi Zhou/distilly](https://github.com/titanwings/distilly)
- Tags: internals
- Published: 2026-09-10

---

**Distilly bundles user-provided skill materials into a validated payload and copies them to host-specific directories, where agent hosts automatically discover and execute the skill package.**

Understanding how data flows through Distilly is essential for developers building portable LLM skills. The `titanwings/distilly` repository implements a multi-stage pipeline that transforms raw user materials—prompts, reference documents, and helper tools—into a standardized bundle consumed by agent hosts like Claude, OpenClaw, and Hermes. This article traces the complete data journey from repository files to active agent execution.

## Stage 1: Assembling the Skill Payload

The data flow begins with the **payload assembly** phase. Distilly defines a complete skill package through the `payloadEntries` array declared in `bin/distilly.mjs` (lines 20–30), which enumerates every file and directory required for a functional skill.

The payload includes:

- **[`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md)** — Metadata manifest containing the skill name, version, description, and required capabilities
- **`prompts/`** — Template files (e.g., [`intake.md`](https://github.com/titanwings/distilly/blob/main/intake.md), [`work_builder.md`](https://github.com/titanwings/distilly/blob/main/work_builder.md)) that drive LLM reasoning
- **`references/`** — Background knowledge documents referenced during execution
- **`tools/`** — Helper scripts written in Python or TypeScript for runtime utilities
- **[`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)** — Python dependencies for the tools directory
- **Licensing and supporting configuration files**

These entries form the complete bundle that Distilly validates and transports to agent hosts.

## Stage 2: Resolving the Target Agent Host

Once the payload is defined, Distilly resolves the installation destination through the **hosts map** defined at lines 32–51 of `bin/distilly.mjs`. This mapping translates friendly host names into concrete filesystem paths on the user's machine.

**Supported host mappings include:**

- `claude-code` → `~/.claude/skills/distilly`
- `openclaw` → `~/.openclaw/workspace/skills/distilly`
- `hermes`, `codex`, and other specialized harnesses

The CLI also supports **aliases** for convenience—`claude` maps to `claude-code`, `deepseek` maps to `deepseek-harness`, and similar shortcuts—allowing users to run `distilly install claude` instead of the full host identifier.

## Stage 3: Validating and Installing the Bundle

The installation logic, implemented in the `validatePayload` and `install` functions (lines 44–67 and 79–86 of `bin/distilly.mjs`), ensures data integrity before copying files to the host directory.

The validation process performs two critical checks:

1. **Existence verification** — Confirms every entry in `payloadEntries` exists in the repository
2. **Version synchronization** — Validates that the version declared in [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) matches the version in [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json)

After validation, the installer creates a **temporary staging directory**, copies every payload entry recursively using `cpSync` (preserving timestamps), and atomically **renames** the staging folder to the target location. If the target directory already exists, Distilly can create a timestamped backup before overwriting when the `--force` flag is provided.

```bash

# Install with automatic backup of existing version

distilly install claude-code --force

```

## Stage 4: Agent Host Discovery and Execution

Once copied, the **agent host** automatically discovers the skill because the destination folder must be named exactly `distilly`—a convention required by all supported hosts. No additional registration code is necessary on the host side.

The host runtime performs the following actions:

1. Reads [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) to extract metadata (name, version, required capabilities)
2. Loads prompt templates from the `prompts/` subdirectory into the LLM context
3. Ingests reference documents from `references/` for retrieval-augmented generation
4. Makes helper scripts in `tools/` available to the execution pipeline

The skill becomes immediately available through the host's UI or API without restart or manual configuration.

## Installation Examples

**Install to a supported host with automatic path resolution:**

```bash
distilly install openclaw

# Copies payload to ~/.openclaw/workspace/skills/distilly

```

**Install to a custom directory bypassing the hosts map:**

```bash
distilly install --path ~/custom/agents/skills/distilly

```

**Validate the payload without installing:**

```bash
distilly --check-package

# Runs validatePayload() and confirms "Distilly package payload is valid."

```

**Check the current package version:**

```bash
distilly --version

# Outputs version from package.json

```

## Key Source Files in the Data Flow

| File | Role | Location |
|------|------|----------|
| `bin/distilly.mjs` | CLI entry point containing `payloadEntries`, `hosts` map, and installation logic | Lines 20–86 |
| [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) | Skill metadata manifest read by both Distilly validator and agent hosts | Repository root |
| `prompts/` | LLM prompt templates copied to host | `prompts/` directory |
| `tools/` | Runtime helper scripts | `tools/` directory |
| [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) | Source of truth for version validation | Repository root |

## Summary

- **Payload assembly** relies on the `payloadEntries` array in `bin/distilly.mjs` to define what constitutes a complete skill package
- **Host resolution** maps friendly names to filesystem paths via the `hosts` variable, supporting aliases for convenience
- **Validation** ensures version consistency between [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) before any files are copied
- **Atomic installation** uses a staging directory and `cpSync` to prevent partial deployments, with optional timestamped backups
- **Host discovery** requires the destination folder to be named `distilly`, enabling automatic loading without host-side configuration

## Frequently Asked Questions

### How does Distilly determine where to install a skill?

Distilly uses the `hosts` map defined in `bin/distilly.mjs` (lines 32–51) to translate command-line arguments like `claude-code` or `openclaw` into absolute filesystem paths. You can override this behavior using the `--path` flag to specify any directory on your system.

### What happens if I install a skill multiple times to the same host?

By default, Distilly will overwrite the existing installation. If you provide the `--force` flag, the installer creates a timestamped backup of the previous version before copying the new payload to `~/.claude/skills/distilly` or the equivalent host directory.

### Why must the destination folder be named `distilly`?

The `distilly` folder name is a hard convention required by all supported agent hosts (Claude, OpenClaw, Hermes, etc.). Hosts scan their skills directories for folders with this specific name and automatically load the [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) metadata and associated resources they find inside.

### Can I verify my skill package before installing it?

Yes. Running `distilly --check-package` executes the `validatePayload()` function, which checks that all files listed in `payloadEntries` exist and that the version in [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) matches [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json). This verification happens entirely within the repository without touching host directories.