# Troubleshooting Plugin Installation Across Different AI Platforms for Lum1104/Understand-Anything

> Troubleshoot plugin installation for Lum1104/Understand-Anything across AI platforms like Claude and VS Code. Master universal Bash installer and automatic discovery methods for seamless integration.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-05-22

---

**TLDR:** The Understand-Anything repository provides a universal Bash installer ([`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh)) that creates symbolic links to enable plugin discovery across Claude, Cursor, VS Code Copilot, Codex, and other AI coding platforms, while Cursor and VS Code support automatic discovery via JSON descriptor files.

The Lum1104/Understand-Anything repository distributes a single plugin package compatible with multiple AI coding assistants. Understanding the core architecture of plugin roots, symlink strategies, and platform-specific detection mechanisms is essential for diagnosing why skills or agents fail to appear in your AI platform's interface.

## Core Architecture of the Plugin System

The plugin system relies on three fundamental components that work across all supported platforms.

### Plugin Root and JSON Descriptors

Each AI platform discovers the plugin through a **plugin root**—a JSON descriptor file that defines the location of skills and agents directories.

- **Cursor** reads [`.cursor-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.cursor-plugin/plugin.json) at the repository root, which points to `./understand-anything-plugin/skills/` and `./understand-anything-plugin/agents/`.
- **VS Code Copilot** reads [`.copilot-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.copilot-plugin/plugin.json), using identical relative paths to the skills and agents folders.

These descriptor files enable auto-discovery when you open the repository folder in the respective editor.

### The Universal Installer Script

The [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) script automates platform detection and creates the appropriate symbolic links. According to the source code in [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) lines 25-38, the script defines a **platform table** that maps platform identifiers to target directories and determines whether to use per-skill or folder-style linking.

For **per-skill platforms**, the script iterates over each subdirectory in `understand-anything-plugin/skills/` and executes:

```bash
ln -sfn "$root/$skill" "$target/$skill"

```

This command appears in lines 23-28 of [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh).

For **folder-style platforms**, the script creates a single symlink to the entire plugin directory:

```bash
ln -sfn "$root" "$target/understand-anything"

```

As implemented in lines 30-33.

After establishing platform-specific links, the installer creates a universal plugin link at `~/.understand-anything-plugin` pointing to the repository's `understand-anything-plugin` directory (lines 69-74). This permanent link allows platforms to locate the plugin without manual configuration.

## Platform-Specific Installation Methods

Each AI platform connects to the Understand-Anything plugin through a specific mechanism defined in the source code.

### Claude Code (Native Marketplace)

**Claude Code** supports native marketplace installation without requiring the Bash script or symlink creation.

```bash
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

```

This method bypasses the [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) architecture entirely, using Claude's built-in plugin registry instead.

### Cursor and VS Code Copilot (Auto-Discovery)

**Cursor** and **VS Code Copilot** automatically discover the plugin when you open the repository folder.

For **Cursor**, the platform recognizes the [`.cursor-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.cursor-plugin/plugin.json) descriptor automatically. Simply clone the repository and open it in Cursor:

```bash
git clone https://github.com/Lum1104/Understand-Anything.git

# Open the folder in Cursor

```

For **VS Code Copilot**, the same pattern applies using [`.copilot-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.copilot-plugin/plugin.json):

```bash
git clone https://github.com/Lum1104/Understand-Anything.git

# Open the folder in VS Code

```

### Copilot CLI (Direct Install)

The **Copilot CLI** supports direct plugin installation via command line without auto-discovery:

```bash
copilot plugin install Lum1104/Understand-Anything:understand-anything-plugin

```

### Bash-Compatible Platforms (Codex, OpenCode, OpenClaw, Antigravity, Gemini CLI, Pi Agent, Vibe CLI, Hermes, Cline, KIMI CLI)

For all other platforms, use the one-line installer script with the platform name as an argument.

**macOS and Linux:**

```bash
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex

```

Replace `codex` with: `opencode`, `openclaw`, `antigravity`, `gemini`, `pi`, `vibe`, `hermes`, `cline`, or `kimi`.

**Windows PowerShell:**

```powershell
iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | iex

```

## Common Installation Failures and Solutions

When skills fail to appear or platforms report missing plugins, verify these specific failure points.

### Skills Not Visible in Platform UI

If the platform interface does not display the Understand-Anything skills, the installer likely created symlinks using the wrong style for your platform.

**Fix:** Re-run the installer specifying the correct platform name. Verify the target path matches the platform table defined in [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) lines 31-38. Check whether your platform requires **per-skill links** (individual skill folders) or **folder-style links** (entire plugin directory).

### Plugin Root Not Found Errors

Cursor or VS Code may fail to locate the plugin if the JSON descriptors are missing or contain incorrect paths.

**Fix:** Confirm that [`.cursor-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.cursor-plugin/plugin.json) or [`.copilot-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.copilot-plugin/plugin.json) exists at the repository root. Verify the `skills` and `agents` fields point to `./understand-anything-plugin/skills/` and `./understand-anything-plugin/agents/` respectively. These paths are version-controlled and should not be modified.

### Stale Symlinks After Repository Changes

Deleting or moving the repository without uninstalling leaves dangling symbolic links that confuse AI platforms.

**Fix:** Clean up stale links using the uninstall flag:

```bash
./install.sh --uninstall codex

```

Replace `codex` with your specific platform identifier. After cleaning, reinstall fresh.

### Permission Errors on macOS and Linux

The installer writes to `$HOME/.understand-anything-plugin` and platform-specific skills directories, which may fail without proper permissions.

**Fix:** Ensure your home directory is writable, or specify an alternate installation location using the `UA_DIR` environment variable before running the script:

```bash
export UA_DIR=/custom/path
./install.sh codex

```

### PowerShell Execution Policy Blocks

Windows systems may block the installer due to default execution policies preventing downloaded scripts from running.

**Fix:** Temporarily bypass the execution policy for the current process:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

```

Alternatively, run the installer from an elevated PowerShell window with administrator privileges.

## Summary

- The Understand-Anything plugin uses **JSON descriptors** ([`.cursor-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.cursor-plugin/plugin.json), [`.copilot-plugin/plugin.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.copilot-plugin/plugin.json)) for auto-discovery in Cursor and VS Code Copilot.
- The **[`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh)** script creates platform-specific symlinks using either per-skill or folder-style linking strategies defined in lines 25-38.
- **Claude Code** uses native marketplace commands, while **Copilot CLI** supports direct installation.
- Stale symlinks and permission errors are the most common failure points, resolvable through the `--uninstall` flag and `UA_DIR` environment variables.

## Frequently Asked Questions

### Why does the installer use symlinks instead of copying files?

The [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) script creates symbolic links rather than copies to ensure that updates to the repository immediately propagate to all connected AI platforms. When you pull new changes or run `./install.sh --update`, the symlinks pointing to `<repo>/understand-anything-plugin` reflect the latest code without requiring reinstallation across Claude, Cursor, Codex, and other supported assistants.

### Can I install the plugin on multiple platforms simultaneously?

Yes. The installer creates separate symlinks for each platform in your `UA_DIR` or default location, while maintaining a single source of truth in the cloned repository at `~/.understand-anything/repo`. You can run `./install.sh codex` followed by `./install.sh cursor` to enable the plugin across multiple AI assistants on the same machine without conflicts.

### How do I verify that the symlinks were created correctly?

Check the platform-specific skills directory listed in the [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh) platform table (lines 31-38). For per-skill platforms, list the contents of the target directory and confirm that subdirectories like `file-analyzer` or `project-scanner` point to `~/.understand-anything/repo/understand-anything-plugin/skills/`. For folder-style platforms, verify that `understand-anything` links to the plugin root directory using `ls -la`.

### What should I do if my AI platform is not listed in the installer?

If your platform (such as a new AI assistant) is not defined in the platform table of [`install.sh`](https://github.com/Lum1104/Understand-Anything/blob/main/install.sh), you can manually create symbolic links following the existing pattern. Create a directory in your platform's skills location and link it to `./understand-anything-plugin/skills/`, or open a pull request to add your platform to the official installer script to support both per-skill and folder-style linking.