# Difference Between Canonical SKILL.md and Packaged Compatibility Copies in CLI-Anything

> Understand the difference between canonical SKILL.md files and packaged compatibility copies in CLI-Anything. Learn how they ensure consistent CLI functionality.

- Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- Tags: deep-dive
- Published: 2026-05-18

---

**CLI-Anything maintains two versions of every skill definition: a canonical file at the repository root that serves as the single source of truth, and a packaged compatibility copy embedded within installed Python wheels to ensure CLI functionality when the source tree is unavailable.**

CLI-Anything uses a dual-file system to bridge active development and production distribution. Understanding the distinction between **canonical SKILL.md** and **packaged compatibility copies** is essential for contributors working within the monorepo and users installing harnesses via pip.

## Canonical vs. Packaged: Core Differences

### Canonical SKILL.md (Repository Root)

The **canonical SKILL.md** resides at `skills/cli-anything-<software>/SKILL.md` in the repository root. This file represents the authoritative skill definition used by the REPL, CI pipelines, and the `npx skills` discovery mechanism. Generated on every build by [`cli-anything-plugin/skill_generator.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/skill_generator.py), this version incorporates the latest changes immediately and remains the primary target for modifications during development.

### Packaged Compatibility Copy (Installed Package)

The **packaged compatibility copy** lives at `cli_anything/<software>/skills/SKILL.md` inside the installed Python package. This read-only snapshot is copied from the canonical file during the build step and bundled with the wheel distribution. It guarantees that pre-installed harnesses—such as `cli-anything-gimp` or `cli-anything-mubu`—function correctly even when the repository root files are absent after a `pip install`.

## Runtime Selection Logic

The `ReplSkin` class in [`cli-anything-plugin/repl_skin.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/repl_skin.py) (lines 41-55) implements the intelligent selection mechanism. At runtime, the CLI walks up the directory tree searching for the repo-root canonical file. If discovered, it loads the authoritative definition; otherwise, it falls back to the packaged copy.

```python

# cli-anything-plugin/repl_skin.py

if skill_path is None:
    package_skill = Path(__file__).resolve().parent.parent / "skills" / "SKILL.md"
    repo_skill = None
    for parent in Path(__file__).resolve().parents:
        candidate = parent / "skills" / self.skill_id / "SKILL.md"
        if candidate.is_file():
            repo_skill = candidate
            break
    if repo_skill and repo_skill.is_file():
        skill_path = str(repo_skill)          # canonical path

    elif package_skill.is_file():
        skill_path = str(package_skill)       # packaged copy

```

## Build Process and Update Cycle

The generation process explicitly links the two versions. As noted in [`cli-anything-plugin/skill_generator.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/skill_generator.py) at line 274, the build system acknowledges: "This CLI is packaged from the canonical `agent-harness` source tree."

The build script generates the canonical path pattern:

```python
skill_path = f"skills/cli-anything-{software_name}/SKILL.md"

```

During packaging, this content is duplicated into `cli_anything/<software>/skills/SKILL.md`, creating the static compatibility snapshot distributed via PyPI.

## Practical Usage Scenarios

### Development Mode (Repository Clone)

When executing CLI-Anything from within the monorepo, commands reference the latest canonical definitions directly:

```bash
npx skills add HKUDS/CLI-Anything --skill cli-anything-gimp -g -y

```

This command scans the root `skills/` directory and exposes the most recent skill definitions to the agent registry.

### Production Mode (Installed Package)

After installation via pip, the CLI operates independently of the source tree:

```bash
pip install cli-anything-gimp
cli-anything-gimp --help

```

In this scenario, `ReplSkin` loads [`cli_anything/gimp/skills/SKILL.md`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_anything/gimp/skills/SKILL.md) because the repo-root canonical file is no longer accessible.

## Summary

- **Canonical SKILL.md** files reside at `skills/cli-anything-<software>/SKILL.md` and serve as the authoritative, continuously updated single source of truth.
- **Packaged compatibility copies** exist at `cli_anything/<software>/skills/SKILL.md` and provide static snapshots for distribution via pip.
- **Runtime selection** in [`cli-anything-plugin/repl_skin.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/repl_skin.py) prioritizes repo-root files when present, falling back to packaged copies for installed wheels.
- **Build integration** ensures both versions remain synchronized, with [`skill_generator.py`](https://github.com/HKUDS/CLI-Anything/blob/main/skill_generator.py) creating the canonical source and the packaging step replicating it into the wheel structure.

## Frequently Asked Questions

### Why does CLI-Anything require two versions of SKILL.md?

The dual-file architecture bridges development and distribution workflows. The canonical file supports active development and immediate updates within the monorepo, while the packaged copy ensures end-users running installed wheels have valid skill definitions without requiring access to the source repository.

### Which file takes precedence when both are available?

When running from the repository, the **canonical SKILL.md** always takes precedence. The `ReplSkin` class explicitly traverses upward from the script location to locate the repo-root file before considering the packaged compatibility copy at `cli_anything/<software>/skills/SKILL.md`.

### How do I update skills in a production installation?

Production installations use the static packaged copy created at build time. To update skill definitions, reinstall the package using `pip install --upgrade cli-anything-<software>`, which pulls the latest canonical definitions and repackages them into the compatibility copy.

### Where is the file selection logic implemented?

The runtime selection logic resides in [`cli-anything-plugin/repl_skin.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli-anything-plugin/repl_skin.py), specifically between lines 41 and 55. This code determines whether to load the canonical repo-root file or fall back to the packaged compatibility copy based on the execution environment.