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

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 and the internal 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. 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 (defining manifest structures and validation helpers) and 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
• Reference documentation from references/ for research-pipeline design patterns

These templates ultimately render into 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: 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: 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 matches the version embedded in SKILL.md
3. The installer copies payload entries—including 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:

# 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 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 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 through to 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), Asset Repository (prompts/), and Support Infrastructure (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 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 matches the 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, 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 artifact consumed by target agents.

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