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

TLDR: Distilly's core structure consists of six specialized packages—bin/, tools/, prompts/, references/, 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, the skill generation engine reads the canonical schema from 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, 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 uses the requests library (declared in 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, prompts/work_analyzer.md, and prompts/merger.md are concatenated by the skill_writer.py script to generate persona descriptions, work analyses, and skill-specific content.

Schema and Documentation Standards (SKILL.md and references/)

The Canonical Skill Schema

The 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 tool uses this file to validate its output before writing 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 and 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)

The 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)

The 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 and 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 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:

# Create a new skill named "my-assistant"

distilly write --name my-assistant

This invokes bin/distilly.mjs, which loads tools/skill_writer.py and renders the skill using templates from prompts/.

Install a generated skill on an OpenClaw server:

# 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, which reads the skill JSON and registers it via the OpenClaw API.

Fetch research data using Python utilities:

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) 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, platform-specific installers like install_openclaw_skill.py, and research utilities in tools/research/.
• The prompts/ package stores Markdown templates such as persona_builder.md that feed LLM generation workflows.
• SKILL.md defines the canonical JSON schema for skill validation, while references/ provides documentation scaffolding and style guides.
• package.json and 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 tool use files from other packages?

The skill_writer.py tool reads the canonical schema defined in 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 and work_analyzer.md—to generate valid skill definitions that conform to the schema.

Why does Distilly include both package.json and requirements.txt?

Distilly uses a dual-language architecture where the CLI and command parsing are implemented in Node.js (managed by package.json), while the heavy-lifting tools for skill generation, installation, and research are implemented in Python (managed by 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 and 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.

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