How to Use distilly_ingest to Store New Subject Material

The distilly_ingest command converts raw documents and transcripts into reusable AI Person Profiles by processing files through ingestion, distillation, and persistence stages, outputting a SKILL.md and .distilly-install.json bundle that agents can discover and invoke.

Distilly is an open-source toolkit hosted at titanwings/distilly that transforms unstructured source material into structured skills for AI agents. The distilly_ingest utility serves as the primary entry point for converting meeting transcripts, chat histories, and personal notes into versioned Person Profiles that capture voice patterns, decision logic, and behavioral judgments.

Understanding the distilly_ingest Architecture

The distilly_ingest workflow is implemented across several modules in the repository. The CLI entry point at bin/distilly.mjs parses the distillyingest sub-command and orchestrates the pipeline, while tools/skill_writer.py handles the final serialization of processed data into installable skill bundles.

The Three-Stage Pipeline

When you execute distilly_ingest, the system processes your source material through three distinct phases:

1. Ingestion – Raw files are read from the source path, normalized, and staged in a temporary work directory (typically /tmp/distilly_{slug}_work_patch.md).
2. Distillation – The core Distilly engine extracts behavioral patterns, voice characteristics, and decision frameworks, applying the JSON schema defined in tools/skill_schema.py where engine.setdefault("name", "distilly") identifies the generation source.
3. Persistence – The resulting manifest is written to your specified output directory as SKILL.md alongside a hidden .distilly-install.json file created by tools/install_generated_skill_common.py, which records the source path, preset version, and engine metadata.

Command-Line Usage Examples

The distilly_ingest command (invoked as distillyingest via the CLI) supports several presets for different relationship types. All examples assume you have cloned the repository and added bin/ to your PATH.

Storing a Colleague Profile

To distill meeting transcripts into a reusable colleague skill:

distillyingest \
  --preset distilly.colleague.v1 \
  --source ./my_notes/meeting_transcripts/ \
  --output ./my_skills/colleague_jane

This creates:

• ./my_skills/colleague_jane/SKILL.md – Human-readable skill definition
• ./my_skills/colleague_jane/.distilly-install.json – Machine-readable metadata with "preset": "distilly.colleague.v1" as validated in tests/test_skill_writer.py

Creating Relationship Skills

For personal chat histories, use the relationship preset:

distillyingest \
  --preset distilly.relationship.v1 \
  --source ./chat_history.txt \
  --output ./my_skills/relationship_anna

The generated .distilly-install.json will contain "preset": "distilly.relationship.v1" alongside the standard engine and generation fields set to "distilly".

Verifying Generated Metadata

Inspect the hidden metadata file to confirm correct generation:

cat ./my_skills/colleague_jane/.distilly-install.json

Expected output structure:

{
  "preset": "distilly.colleague.v1",
  "engine": {"name": "distilly"},
  "generation": {"engine": "distilly"},
  "source": "my_notes/meeting_transcripts/"
}

Installing Skills for AI Agents

Move the generated skill to an agent's discovery path. For Claude:

cp -r ./my_skills/colleague_jane ~/.claude/skills/distilly

Agents discover these skills via standard lookup paths including ~/.agents/skills/distilly and ~/.openclaw/workspace/skills/distilly, invoking them through the $distilly or /skill:distilly entry points.

Configuration and Schema Details

The Distilly engine embeds its identity directly into the skill schema. In tools/skill_schema.py, the schema enforces engine.name = "distilly" and generation.engine = "distilly", ensuring downstream agents can verify provenance. Configuration files for collectors (such as Slack integrations) reside in ~/.distilly/slack_config.json and other home-directory paths.

Summary

• distilly_ingest converts raw source material into structured AI skills through a three-stage pipeline implemented in bin/distilly.mjs and tools/skill_writer.py.
• The command generates two critical files: SKILL.md for human readability and .distilly-install.json for machine verification, with presets like distilly.colleague.v1 and distilly.relationship.v1.
• All generated skills carry the engine.name: "distilly" identifier, enabling discovery in standard paths such as ~/.claude/skills/distilly.
• The process creates temporary work patches in /tmp/ before persisting final artifacts to your specified output directory.

Frequently Asked Questions

What file formats can distilly_ingest process?

According to the ingestion stage in bin/distilly.mjs, the tool reads raw text files, transcripts, and message exports. The normalization phase handles various encodings before staging content in the temporary work patch file, though specific MIME type restrictions depend on your installed collector configurations in ~/.distilly/.

Where does distilly_ingest store temporary files during processing?

During the distillation stage, the CLI creates temporary work patches at /tmp/distilly_{slug}_work_patch.md where {slug} represents a sanitized identifier derived from your output path. These intermediate files are automatically cleaned up after the skill writer in tools/skill_writer.py successfully generates the final SKILL.md and .distilly-install.json bundle.

How do I verify that a skill was generated correctly?

Check the .distilly-install.json hidden file in your output directory. As validated by tests/test_skill_writer.py, this JSON must contain the preset field matching your command-line argument (e.g., distilly.colleague.v1), the engine.name set to "distilly", and the source path reference. Missing these fields indicates a pipeline failure in either the schema application or the install generation step handled by tools/install_generated_skill_common.py.

Can I use custom presets beyond colleague and relationship types?

The current implementation in tools/skill_schema.py supports three validated presets: distilly.colleague.v1, distilly.relationship.v1, and distilly.celebrity.v1. While the architecture in bin/distilly.mjs accepts arbitrary preset strings, the skill writer and test suite (tests/test_skill_writer.py) specifically validate against these three versions. Extending support requires modifying the schema validation and adding corresponding test cases to ensure proper metadata generation.

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