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

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, 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 (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.

# 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 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:

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:

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:

pip install cli-anything-gimp
cli-anything-gimp --help

In this scenario, ReplSkin loads 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 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 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, 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.

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