# How the Codex Plugin Lifecycle Works in Distilly

> Explore the Distilly Codex plugin lifecycle. Learn how install, discover, and invoke phases automatically load skills from ~/.agents/skills.

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

---

**Distilly treats the Codex host as a native Skill destination, implementing a three-phase lifecycle—install, discover, and invoke—that automatically loads skills from `~/.agents/skills` once the Distilly installer copies the repository files.**

The **Codex plugin lifecycle** in the `titanwings/distilly` repository enables seamless integration between Distilly-generated skills and OpenAI’s Codex CLI. Rather than requiring manual configuration, Distilly provides dedicated installer scripts that manage the entire deployment process, from copying files to the correct directory structure to enabling real-time invocation within Codex sessions.

## The Three Phases of the Codex Plugin Lifecycle

The lifecycle consists of three distinct phases that transform a Distilly skill into a callable Codex command. Each phase is handled by specific components within the Distilly toolchain, ensuring that skills remain synchronized with their source repositories.

### Install Phase

During the **install** phase, Distilly copies the skill repository into Codex’s native skill directory. The repository provides two specialized installers in the `tools/` directory to handle different deployment scenarios.

**Development installation** uses [`tools/install_codex_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_codex_skill.py), which copies the entire repository—including [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), prompts, and source artifacts—into `~/.agents/skills/<skill-id>`. The core logic resides in the `install_skill()` function, which respects the `--force` flag to overwrite existing installations and the `--dry-run` flag to preview changes without modifying the filesystem. After copying, the installer writes a hidden [`.distilly-install.json`](https://github.com/titanwings/distilly/blob/main/.distilly-install.json) file for debugging and returns the final destination path.

**Production installation** uses [`tools/install_codex_generated_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_codex_generated_skill.py), a thin wrapper that calls the generic installer with `host="codex"` specified. This script copies only a generated combined skill (typically produced after running `distilly build`) rather than the full development repository.

The CLI entry point in [`tools/skill_writer.py`](https://github.com/titanwings/distilly/blob/main/tools/skill_writer.py) registers the `--install-codex-skill` flag and forwards the destination path via `args.codex_skills_dir`, bridging Distilly’s build commands with Codex’s installation requirements.

```bash

# Development mode: Install the full repository

python3 tools/install_codex_skill.py --force

# Production mode: Install a generated combined skill

python3 tools/install_codex_generated_skill.py \
    --skill-dir ./distilly-output/celebrity-zhou-qimo \
    --codex-skills-dir ~/.agents/skills \
    --force

```

### Discover Phase

The **discover** phase occurs within Codex itself. Codex continuously monitors the `~/.agents/skills` directory for sub-folders containing a [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) file. When Codex starts or when the user executes the `/skills` command, the CLI scans each subdirectory, reads the [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) manifest, and builds a command name derived from the folder name (for example, `celebrity-zhou-qimo`).

Distilly’s responsibility during this phase is limited to ensuring the folder layout matches Codex’s rigid expectations. As documented in [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) within the Distilly repository, the skill must reside in its own subdirectory with a valid [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) at the root for automatic discovery to succeed.

### Invoke Phase

Once discovered, the skill enters the **invoke** phase, where users can trigger Distilly functionality through two primary mechanisms:

- **Direct invocation**: Type `$distilly` (or the specific command name derived from the folder) in the Codex prompt to execute the skill immediately. If the repository contains multiple characters, Codex falls back to the skill’s primary command name.
- **Interactive selection**: Use Codex’s `/skills` UI to browse available skills and select Distilly from the list.

When invoked, Codex loads the skill’s entry point—typically `distilly.mjs`—and executes the prompts defined in the Distilly skill configuration. The exact invocation syntax and parameter handling are documented in the **Codex** section of [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md).

## Installing Distilly Skills for Codex

The installation workflow differs depending on whether you are developing a skill or deploying a finalized version.

**For development**, use the full repository installer to enable rapid iteration:

```bash
python3 tools/install_codex_skill.py --force

```

This copies the entire working directory, allowing you to modify prompts and immediately test changes by reinstalling with `--force`.

**For production**, build the skill first, then install the generated output:

```bash

# First, generate the combined skill

distilly build

# Then install only the generated artifacts

python3 tools/install_codex_generated_skill.py \
    --skill-dir ./output/celebrity-zhou-qimo \
    --codex-skills-dir ~/.agents/skills \
    --force

```

The test suite in [`tests/test_install_openclaw_and_codex.py`](https://github.com/titanwings/distilly/blob/main/tests/test_install_openclaw_and_codex.py) validates both workflows, verifying correct directory copying, flag handling, and path resolution to ensure the installer behaves predictably across environments.

## Summary

- **Three-phase lifecycle**: Distilly skills move through **install** (file copying), **discover** (Codex scanning), and **invoke** (user execution) phases.
- **Dual installer architecture**: Use [`install_codex_skill.py`](https://github.com/titanwings/distilly/blob/main/install_codex_skill.py) for development environments and [`install_codex_generated_skill.py`](https://github.com/titanwings/distilly/blob/main/install_codex_generated_skill.py) for production deployments.
- **Automatic discovery**: Codex watches `~/.agents/skills` for folders containing [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md), requiring no manual registration after installation.
- **Two invocation methods**: Skills can be called directly with the `$` prefix (e.g., `$distilly`) or selected interactively via `/skills`.
- **Version control**: Re-running the installer with `--force` overwrites existing skills, allowing Codex to pick up updates on the next load.

## Frequently Asked Questions

### What is the difference between install_codex_skill.py and install_codex_generated_skill.py?

[`tools/install_codex_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_codex_skill.py) copies the entire Distilly repository—including source code, prompts, and build artifacts—making it ideal for development when you need to iterate on skill logic. In contrast, [`tools/install_codex_generated_skill.py`](https://github.com/titanwings/distilly/blob/main/tools/install_codex_generated_skill.py) is a specialized wrapper that installs only the combined output generated by `distilly build`, intended for production use where you want to minimize the installation footprint to only the files necessary for execution.

### How does Codex know when a Distilly skill has been updated?

Codex does not actively monitor for changes after initial discovery. To update a skill, re-run the appropriate installer script with the `--force` flag to overwrite the existing directory in `~/.agents/skills`. Codex will then load the updated version the next time the skill is invoked or when the Codex CLI restarts.

### Where does Codex look for Distilly skills?

Codex scans the `~/.agents/skills` directory (configurable via `--codex-skills-dir` in Distilly’s installer) for subdirectories containing a [`SKILL.md`](https://github.com/titanwings/distilly/blob/main/SKILL.md) file. The folder name becomes the skill’s command identifier, so Distilly’s installer ensures the directory structure matches this expectation exactly, placing the skill metadata and entry points in the correct locations.

### Can I test the installation before copying files?

Yes. Both installer scripts support the `--dry-run` flag, which simulates the installation process and prints the intended copy operations without modifying the filesystem. This allows you to verify the destination path and file list before committing changes to the Codex skills directory.