How the Codex Plugin Lifecycle Works in Distilly

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, which copies the entire repository—including 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 file for debugging and returns the final destination path.

Production installation uses 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 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.

# 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 file. When Codex starts or when the user executes the /skills command, the CLI scans each subdirectory, reads the 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 within the Distilly repository, the skill must reside in its own subdirectory with a valid 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.

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:

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:

# 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 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 for development environments and install_codex_generated_skill.py for production deployments.
• Automatic discovery: Codex watches ~/.agents/skills for folders containing 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 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 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 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.

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