How Data Flows Through Distilly from User Materials to Agent Hosts

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 — Metadata manifest containing the skill name, version, description, and required capabilities
• prompts/ — Template files (e.g., intake.md, 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 — 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 matches the version in 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.

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

distilly install openclaw

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

Install to a custom directory bypassing the hosts map:

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

Validate the payload without installing:

distilly --check-package

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

Check the current package version:

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	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	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 and 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 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 matches package.json. This verification happens entirely within the repository without touching host directories.

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