# What Are the Purposes of Each Package in Distilly's Core Structure?

> Explore Distilly's core structure and discover the purpose of each package including bin tools prompts references and configuration manifests for AI skills.

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

---

**TLDR:** Distilly's core structure consists of six specialized packages—`bin/`, `tools/`, `prompts/`, `references/`, [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), and configuration manifests—that collectively handle CLI parsing, skill generation, LLM templating, schema validation, and cross-platform installation for AI skills.

The `titanwings/distilly` repository is organized around a small number of core packages that implement the CLI, skill-definition schema, and tooling required to generate, install, and test AI "skills." Understanding the **purposes of each package in Distilly's core structure** is essential for developers who want to extend the tool or debug the skill-generation pipeline. Each folder and configuration file serves a specific architectural role, from command-line argument parsing to Python-based research utilities.

## CLI Entry Point (`bin/`)

The **`bin/`** directory serves as the executable entry point of the tool. At **`bin/distilly.mjs`**, the CLI driver parses command-line arguments, dispatches sub-commands such as `install`, `write`, and `test`, and performs sanity checks like the **`--check-package`** hook before any operation executes. This Node.js module acts as the router that forwards user instructions to the appropriate Python-based implementation modules in the `tools/` directory.

## Implementation Toolkit (`tools/`)

The **`tools/`** directory contains the heavy-lifting implementation modules written in Python. These scripts handle skill creation, installation, and external data gathering, with each file focusing on a specific AI platform or workflow.

### Skill Generation Engine

At **[`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py)**, the skill generation engine reads the canonical schema from [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and renders a complete skill definition. It concatenates prompt templates from the `prompts/` folder to generate the JSON structure required for AI personas and behaviors.

### Platform-Specific Installers

The `tools/` directory includes multiple installer scripts for deploying skills to different AI platforms. Files such as **[`tools/install_openclaw_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_openclaw_skill.py)**, along with variants for Hermes, Codex, and Claude, handle the API communication required to register generated skills on target servers.

### Research and Data Gathering

The **`tools/research/`** subdirectory provides utilities for gathering and cleaning external data that can populate a skill's knowledge base. For example, **[`tools/research/xquik_public_posts.py`](https://github.com/titanwings/distilly/blob/main/tools/research/xquik_public_posts.py)** uses the `requests` library (declared in [`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)) to fetch public posts for analysis.

## LLM Prompt Templates (`prompts/`)

The **`prompts/`** directory stores plain-text Markdown files that serve as reusable prompt chunks for Large Language Models. Files such as **[`prompts/persona_builder.md`](https://github.com/titanwings/distilly/blob/main/prompts/persona_builder.md)**, **[`prompts/work_analyzer.md`](https://github.com/titanwings/distilly/blob/main/prompts/work_analyzer.md)**, and **[`prompts/merger.md`](https://github.com/titanwings/distilly/blob/main/prompts/merger.md)** are concatenated by the [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) script to generate persona descriptions, work analyses, and skill-specific content.

## Schema and Documentation Standards ([`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and `references/`)

### The Canonical Skill Schema

The **[`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md)** file at the repository root defines the canonical schema describing a "skill." It specifies the JSON structure—sections for *persona*, *knowledge*, and *behaviour*—that all generated skills must follow. The [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) tool uses this file to validate its output before writing [`skill.json`](https://github.com/titanwings/distilly/blob/main/skill.json) files to disk.

### Documentation Scaffolding

The **`references/`** directory provides human-readable documentation scaffolding and sample templates. Files such as **[`references/celebrity_budget_unfriendly_template.md`](https://github.com/titanwings/distilly/blob/main/references/celebrity_budget_unfriendly_template.md)** and **[`references/SKILL_TYPE_ABSTRACTION_DESIGN.md`](https://github.com/titanwings/distilly/blob/main/references/SKILL_TYPE_ABSTRACTION_DESIGN.md)** serve as style guides and example skill definitions, ensuring generated content remains consistent with the project's design guidelines.

## Package Manifests and Dependencies

### Node.js Configuration ([`package.json`](https://github.com/titanwings/distilly/blob/main/package.json))

The **[`package.json`](https://github.com/titanwings/distilly/blob/main/package.json)** file serves as the npm package manifest that makes Distilly publishable as a Node module. It declares the binary entry point (`bin`), the files to ship, and the Node engine requirement, including a **`scripts.prepack`** hook to ensure correct bundling before publishing.

### Python Environment ([`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt))

The **[`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)** file lists Python dependencies required by the `tools/` scripts, including **`pydantic`** for data validation, **`pytest`** for testing, and **`beautifulsoup4`** for web scraping in the research modules. This dual-language approach—Node.js for the CLI and Python for tooling—requires both [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) and [`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt) to maintain reproducible environments.

## How Distilly's Packages Interact

The packages operate in a specific pipeline to transform user commands into deployed AI skills:

1. **CLI (`bin/`)** parses the command and forwards work to the appropriate Python module in `tools/`.
2. **Tool modules (`tools/`)** read the skill schema from [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and fill it using prompt templates from `prompts/`.
3. **Generated output** is written as JSON to disk, optionally packaged, and installed via installer scripts targeting specific AI platforms.
4. **Reference files** provide developers with clear examples of expected output, maintaining consistency with the project's abstraction design guidelines.

## Practical Usage Examples

Below are runnable examples demonstrating how the core packages function in practice.

Generate a new skill using the CLI and skill writer:

```bash

# Create a new skill named "my-assistant"

distilly write --name my-assistant

```

This invokes `bin/distilly.mjs`, which loads [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py) and renders the skill using templates from `prompts/`.

Install a generated skill on an OpenClaw server:

```bash

# Install to an OpenClaw server

distilly install openclaw --skill ./my-assistant/skill.json --host https://openclaw.example.com

```

The command dispatches to [`tools/install_openclaw_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_openclaw_skill.py), which reads the skill JSON and registers it via the OpenClaw API.

Fetch research data using Python utilities:

```python
from tools.research.xquik_public_posts import fetch_posts

posts = fetch_posts(query="AI persona design", max_results=5)
print(posts[0].title)

```

This helper uses `requests` (from [`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)) to retrieve data for incorporation into a skill's knowledge base.

## Summary

- The **`bin/`** package provides the Node.js CLI entry point at `bin/distilly.mjs` for command parsing and dispatch.
- The **`tools/`** package contains Python implementation modules including [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py), platform-specific installers like [`install_openclaw_skill.py`](https://github.com/titanwings/distilly/blob/main/install_openclaw_skill.py), and research utilities in `tools/research/`.
- The **`prompts/`** package stores Markdown templates such as [`persona_builder.md`](https://github.com/titanwings/distilly/blob/main/persona_builder.md) that feed LLM generation workflows.
- **[`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md)** defines the canonical JSON schema for skill validation, while **`references/`** provides documentation scaffolding and style guides.
- **[`package.json`](https://github.com/titanwings/distilly/blob/main/package.json)** and **[`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)** manage Node.js and Python dependencies respectively, supporting the tool's dual-language architecture.

## Frequently Asked Questions

### What is the purpose of the `bin/distilly.mjs` file in Distilly?

The `bin/distilly.mjs` file serves as the CLI driver and entry point for the entire tool. It parses command-line arguments, validates inputs through hooks like `--check-package`, and dispatches sub-commands such as `write`, `install`, and `test` to the appropriate Python modules in the `tools/` directory.

### How does the [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) tool use files from other packages?

The [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py) tool reads the canonical schema defined in [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) to understand the required JSON structure for skills. It then loads and concatenates prompt templates from the `prompts/` directory—such as [`persona_builder.md`](https://github.com/titanwings/distilly/blob/main/persona_builder.md) and [`work_analyzer.md`](https://github.com/titanwings/distilly/blob/main/work_analyzer.md)—to generate valid skill definitions that conform to the schema.

### Why does Distilly include both [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) and [`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)?

Distilly uses a dual-language architecture where the CLI and command parsing are implemented in Node.js (managed by [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json)), while the heavy-lifting tools for skill generation, installation, and research are implemented in Python (managed by [`requirements.txt`](https://github.com/titanwings/distilly/blob/main/requirements.txt)). This separation allows the tool to leverage npm for distribution while using Python's rich ecosystem for AI and data processing tasks.

### What types of files are stored in the `references/` package?

The `references/` directory contains documentation scaffolding and sample templates rather than executable code. It includes files like [`celebrity_budget_unfriendly_template.md`](https://github.com/titanwings/distilly/blob/main/celebrity_budget_unfriendly_template.md) and [`SKILL_TYPE_ABSTRACTION_DESIGN.md`](https://github.com/titanwings/distilly/blob/main/SKILL_TYPE_ABSTRACTION_DESIGN.md), which serve as style guides and example skill definitions to help developers understand the expected output format and maintain design consistency.