# How to Use distilly_ingest to Store New Subject Material

> Learn how to use distilly_ingest to store new subject material. This command processes documents into AI Person Profiles for agents to use. Explore the titanwings/distilly repository today.

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

---

**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`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.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`](https://github.com/titanwings/distilly/blob/main/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`](https://github.com/titanwings/distilly/blob/main/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`](https://github.com/titanwings/distilly/blob/main/SKILL.md) alongside a hidden [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.distilly-install.json) file created by [`tools/install_generated_skill_common.py`](https://github.com/titanwings/distilly/blob/main/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:

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

```

This creates:

- [`./my_skills/colleague_jane/SKILL.md`](https://github.com/titanwings/distilly/blob/main/./my_skills/colleague_jane/SKILL.md) – Human-readable skill definition
- [`./my_skills/colleague_jane/.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/./my_skills/colleague_jane/.distilly-install.json) – Machine-readable metadata with `"preset": "distilly.colleague.v1"` as validated in [`tests/test_skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tests/test_skill_writer.py)

### Creating Relationship Skills

For personal chat histories, use the relationship preset:

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

```

The generated [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.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:

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

```

Expected output structure:

```json
{
  "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:

```bash
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`](https://github.com/titanwings/distilly/blob/main/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`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py).
- The command generates two critical files: [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) for human readability and [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.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`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py) successfully generates the final [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) and [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.distilly-install.json) bundle.

### How do I verify that a skill was generated correctly?

Check the [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.distilly-install.json) hidden file in your output directory. As validated by [`tests/test_skill_writer.py`](https://github.com/titanwings/distilly/blob/main/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`](https://github.com/titanwings/distilly/blob/main/tools/install_generated_skill_common.py).

### Can I use custom presets beyond colleague and relationship types?

The current implementation in [`tools/skill_schema.py`](https://github.com/titanwings/distilly/blob/main/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`](https://github.com/titanwings/distilly/blob/main/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.