# Distilly Monorepo Architecture: Inside the Four-Layer AI Skill Platform

> Explore the Distilly monorepo architecture featuring a four-layer design for AI skill platforms. Discover its Node CLI, Python engine, prompt assets, and CI/CD for agent profiles.

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

---

**The Distilly monorepo follows a four-layer architecture bundling a Node-based CLI installer, a Python skill generation engine, static prompt assets, and CI/CD infrastructure to create, version, and install AI-agent Person Profiles across multiple host platforms.**

The `titanwings/distilly` repository is a self-contained monorepo designed to manage "Skills"—versioned AI-agent Person Profiles—through a unified codebase that handles everything from content generation to distribution. Understanding the Distilly monorepo architecture reveals how a single repository can orchestrate complex workflows spanning multiple programming languages and deployment targets.

## Four-Layer Architecture Overview

The repository organizes functionality into four distinct logical layers, each handling a specific concern in the skill lifecycle.

### CLI and Installer Layer

The entry point for all user interactions is `bin/distilly.mjs`, a compact Node.js ES-module that functions as both the command-line interface and installation engine. This script parses commands like `distilly install <host>` and manages the deployment of skill payloads to discovery directories used by supported AI agents including Claude-Code, OpenClaw, Hermes, Codex, DeepSeek, Pi, Grok-Build, and OpenCode.

Key implementation details in this layer include:

- **Host resolution**: Lines 33-44 define a `hosts` map that resolves target installation directories for each supported agent platform
- **Payload validation**: The `validatePayload()` function (lines 80-90) enforces version consistency between [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) and the internal [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) manifest
- **Backup logic**: Before copying new skill versions, the installer archives existing payloads to prevent data loss

### Skill Generation Engine

At the core of the Distilly monorepo architecture sits a pure-Python engine located in [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py). This module orchestrates the creation and mutation of skill artefacts including Markdown documentation, JSON manifests, and versioning metadata.

The engine exposes two primary operations:

- **`create_skill()`** (lines 70-84): Initializes new skill directories with subfolders for `knowledge/`, `versions/`, and generates initial artefacts including `work_doc`, `persona_doc`, and `combined_skill`
- **`update_skill()`** (lines 94-140): Handles incremental updates by merging markdown patches, applying correction logs, and archiving previous versions under `versions/<old-ver>/`

Supporting modules include [`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_schema.py) (defining manifest structures and validation helpers) and [`tools/skill_presets.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_presets.py) (containing preset configurations for the three character families: colleague, relationship, and celebrity).

### Asset and Prompt Repository

Static resources reside in the `prompts/` and `references/` directories, feeding content into the generation process. The `prompts/` folder contains multilingual Markdown templates organized by character family and language preference.

The Python engine selects appropriate templates based on:

- Character family classification (colleague, relationship, or celebrity)
- Language preferences detected via `prefers_chinese()` in [`skill_writer.py`](https://github.com/titanwings/distilly/blob/main/skill_writer.py)
- Reference documentation from `references/` for research-pipeline design patterns

These templates ultimately render into [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), the canonical skill definition consumed by AI agents at runtime.

### Support and Distribution Infrastructure

The final layer ensures the repository remains testable, publishable, and CI/CD-ready. Key components include:

- **[`package.json`](https://github.com/titanwings/distilly/blob/main/package.json)**: Declares the package as an ES-module (`"type": "module"`), defines the npm entry point, and includes a `prepack` script that runs `distilly.mjs --check-package` to verify payload integrity before GitHub Packages publication
- **[`.github/workflows/ci.yml`](https://github.com/titanwings/distilly/blob/main/.github/workflows/ci.yml)**: Orchestrates continuous integration, running the Python test suite and validating installer functionality
- **`tests/`**: Contains unit tests verifying the Python generation engine's behavior across edge cases

## How the Components Integrate

### Installation Workflow

When a user executes `distilly install claude-code`, the system follows a precise sequence:

1. The Node CLI resolves the host target using the internal `hosts` map
2. `validatePayload()` checks that the version declared in [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) matches the version embedded in [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md)
3. The installer copies payload entries—including [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), `prompts/`, and `tools/`—into the agent's discovery directory
4. Existing installations are backed up automatically before replacement

### Generation and Versioning Pipeline

Content creation flows through the Python engine with strict versioning semantics:

```bash

# Create a new celebrity skill profile

distilly \
  --action create \
  --slug karpathy \
  --name "Andrej Karpathy" \
  --character celebrity \
  --work work.md \
  --persona persona.md

```

This invokes `create_skill()`, which normalizes metadata using [`skill_schema.py`](https://github.com/titanwings/distilly/blob/main/skill_schema.py) helpers, selects appropriate templates from `prompts/`, and generates the directory structure. Subsequent updates trigger `update_skill()`, which:

- Parses markdown patches via `--work-patch` and `--persona-patch` flags
- Archives the current version to `versions/<old-ver>/` before applying changes
- Rewrites all artefacts while preserving backward-compatible fields through `sync_legacy_fields()`

### Package Integrity and Distribution

Before any npm publication, the `prepack` lifecycle hook executes `distilly.mjs --check-package` (defined in [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) lines 21-23). This ensures that generated payloads remain synchronized with the declared package version, preventing mismatched releases.

## Key Implementation Patterns

The Distilly monorepo architecture employs several sophisticated patterns to maintain consistency across languages and platforms:

- **Single-source-of-truth versioning**: Version identifiers propagate from [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) through to [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) validation, ensuring downstream agents receive correctly labeled artifacts
- **Multilingual template resolution**: The `prefers_chinese()` utility function enables runtime selection between English and Chinese prompt templates without duplicating generation logic
- **Incremental archiving**: The `versions/` subdirectory structure maintains complete historical records of skill evolution, enabling rollback capabilities without external version control dependencies

## Summary

- **Four-layer design**: The repo separates concerns into CLI/Installer (`bin/distilly.mjs`), Generation Engine ([`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py)), Asset Repository (`prompts/`), and Support Infrastructure ([`package.json`](https://github.com/titanwings/distilly/blob/main/package.json), CI/CD)
- **Cross-language coordination**: Node.js handles installation and packaging while Python manages content generation and versioning
- **Strict validation**: `validatePayload()` enforces version consistency between npm metadata and skill manifests at lines 80-90 of the installer script
- **Incremental updates**: The `update_skill()` function (lines 94-140) archives previous versions and applies markdown patches atomically
- **Multi-host support**: A single payload deploys to Claude-Code, Codex, DeepSeek, and five other agent platforms through the `hosts` map (lines 33-44)

## Frequently Asked Questions

### What programming languages does the Distilly monorepo use?

The architecture combines **Node.js** for the CLI installer and package management with **Python** for the skill generation engine. The installer script `bin/distilly.mjs` handles cross-platform file operations and host detection, while [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py) manages complex content generation, versioning logic, and template rendering.

### How does Distilly handle versioning for AI skills?

Versioning operates through a dual-check system: `validatePayload()` ensures the npm version in [`package.json`](https://github.com/titanwings/distilly/blob/main/package.json) matches the [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) internal version before installation. During updates, `update_skill()` automatically archives the existing skill to a `versions/<old-ver>/` directory before applying new patches, creating an immutable history of profile changes.

### Which AI agent platforms does the Distilly installer support?

The `hosts` map defined at lines 33-44 of `bin/distilly.mjs` supports Claude-Code, OpenClaw, Hermes, Codex, DeepSeek, Pi, Grok-Build, and OpenCode. Each entry points to platform-specific discovery directories where the installer copies the standardized skill payload consisting of [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), prompt templates, and tool definitions.

### Where are the prompt templates stored in the repository?

Multilingual prompt templates reside in the `prompts/` directory, organized by character family (colleague, relationship, celebrity) and language. The Python engine selects templates at runtime based on the `--character` flag and language preferences detected through `prefers_chinese()`, rendering final content into the [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) artifact consumed by target agents.