Using the 'uloop' CLI and Skills
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- Packages/src/Cli~/src/cli.ts
- Packages/src/Cli~/src/skills/skills-command.ts
- Packages/src/Cli~/scripts/generate-bundled-skills.ts
- Packages/src/Cli~/src/tests/skills-manager.test.ts
- Packages/src/Cli~/src/Editor/Api/McpTools/ExecuteDynamicCode/SKILL.md
- Packages/src/Cli~/package.json
- Packages/src/Cli~/src/tests/cli-e2e.test.ts
- Packages/src/ARCHITECTURE.md
- Packages/src/TOOL_REFERENCE.md
The uloop command-line interface (CLI) is a standalone tool that provides direct communication with a Unity Editor running the uLoopMCP package. It is designed to be invoked by AI agents and LLM tools, offering an alternative to the standard Model Context Protocol (MCP) server setup. A key feature of the CLI is its integration with "Skills," which allows LLM tools to automatically discover and utilize the CLI's capabilities without manual configuration.
This system exposes Unity Editor functions—such as compiling, running tests, and inspecting the scene—as simple command-line tools. By installing the associated Skills, LLM tools become aware of these commands and can use them to perform autonomous development loops within a Unity project. This approach is context-efficient and simplifies the integration between AI development environments and Unity.
Sources: README.md, Packages/src/Cli~/src/cli.ts
CLI Architecture and Workflow
The uloop CLI is a Node.js application that acts as a client to the TCP server running inside the Unity Editor. It dynamically generates its own subcommands based on the tools exposed by the Unity instance, ensuring that the CLI is always in sync with the available editor functionalities.
Sources: Packages/src/Cli~/package.json, Packages/src/ARCHITECTURE.md
Dynamic Command Registration
The CLI does not have hardcoded commands for Unity tools. Instead, it uses a local cache (.uloop/tools.json) to define its command structure at runtime. This allows for great flexibility, as new tools added to the Unity project can be exposed to the CLI without updating the CLI tool itself.
The following diagram illustrates the workflow for syncing and registering commands.
This diagram shows how the uloop sync command fetches tool definitions from Unity and how the CLI uses the resulting cache to build its commands on startup.
Sources: Packages/src/Cli~/src/cli.ts:52-55, Packages/src/Cli~/src/cli.ts:299-322
If an unknown command is executed, the CLI automatically triggers the sync process in an attempt to find the new command before failing.
Sources: Packages/src/Cli~/src/cli.ts:490-508
Error Handling
The CLI includes specific error handling for common Unity states, providing user-friendly feedback when the Unity editor is busy. This prevents ambiguous connection errors and helps the user understand the current state of the editor.
UNITY_COMPILING: Displayed when Unity is compiling scripts.UNITY_DOMAIN_RELOAD: Displayed when a domain reload is in progress.UNITY_SERVER_STARTING: Displayed when the uLoopMCP server in Unity is starting up.UNITY_NO_RESPONSE: Displayed when Unity is busy and does not respond in time.ECONNREFUSED: A generic connection error indicating the Unity server is likely not running.
Sources: Packages/src/Cli~/src/cli.ts:221-250
Built-in CLI Commands
The uloop CLI comes with a set of built-in commands for management and utility purposes. These commands are always available and are not dependent on the tools synced from Unity.
| Command | Description |
|---|---|
list | Lists all available tool commands that can be executed, as fetched from Unity. |
sync | Fetches the latest tool definitions from the Unity Editor and updates the local .uloop/tools.json cache. |
skills | A subcommand for managing Skills (see Skill Management). |
completion | Generates and optionally installs shell completion scripts for bash, zsh, and powershell. |
update | Updates the uloop-cli package to the latest version via npm. |
fix | Cleans up stale lock files (compiling.lock, domainreload.lock, etc.) in the project's Temp directory that might prevent the CLI from connecting. |
Sources: Packages/src/Cli~/src/cli.ts:38-76
Skills System
Skills are the mechanism that allows LLM-powered tools (like Claude Code) to discover and use uloop commands. A Skill is essentially a set of markdown files that document a CLI command in a machine-readable format.
Sources: README.md
Skill Definition (SKILL.md)
Each skill is defined by a SKILL.md file. This file contains a YAML frontmatter block and markdown content that describes the command, its purpose, and its parameters.
Key frontmatter fields:
| Field | Type | Description |
|---|---|---|
name | string | The unique name of the skill, which corresponds to the CLI command (e.g., uloop-execute-dynamic-code). |
description | string | A detailed description of what the tool does and when an AI should use it. |
internal | boolean | If true, this skill will be excluded from the installation process. Useful for debugging or internal tools. |
Sources: Packages/src/Cli~/src/Editor/Api/McpTools/ExecuteDynamicCode/SKILL.md:1-4, Packages/src/Cli~/src/tests/skills-manager.test.ts:15-23, Packages/src/Cli~/scripts/generate-bundled-skills.ts:200-203
Example of a SKILL.md file:
---
name: uloop-execute-dynamic-code
description: Execute C# code dynamically in Unity Editor via uloop CLI. Use for editor automation: (1) Prefab/material wiring and AddComponent operations, (2) Reference wiring with SerializedObject, (3) Scene/hierarchy edits and batch operations. NOT for file I/O or script authoring.
---
# uloop execute-dynamic-code
Execute C# code dynamically in Unity Editor.
## Usage
```bash
uloop execute-dynamic-code --code '<c# code>'
...
*Sources: [Packages/src/Cli~/src/Editor/Api/McpTools/ExecuteDynamicCode/SKILL.md](https://github.com/hatayama/unity-cli-loop/blob/HEAD/Packages/src/Cli~/src/Editor/Api/McpTools/ExecuteDynamicCode/SKILL.md)*
### Skill Discovery and Bundling
The project includes a build script that automatically discovers `SKILL.md` files and bundles them into a single TypeScript file for distribution with the CLI.
The discovery process scans the following locations:
- `Packages/src/Editor/Api/McpTools/<ToolFolder>/SKILL.md`
- `Packages/src/Cli~/src/skills/skill-definitions/cli-only/<SkillFolder>/SKILL.md`
- Project-specific skills in `Assets/**/Editor/<FolderName>/SKILL.md` and `Packages/*/Editor/<FolderName>/SKILL.md`
The following diagram shows the bundling process:
This process ensures that all available skills are packaged with the CLI, ready for installation into an LLM tool's environment.
Sources: Packages/src/Cli~/package.json:11, Packages/src/Cli~/scripts/generate-bundled-skills.ts
Skill Management (uloop skills ...)
The uloop skills command is the primary interface for managing the installation of skills for different AI tools. It can install, uninstall, and list the status of skills.
Sources: Packages/src/Cli~/src/skills/skills-command.ts:18-21
The following sequence diagram illustrates the install command flow:
This shows how the command installs both bundled and project-specific skills into the target directory.
Sources: Packages/src/Cli~/src/skills/skills-command.ts:40-50, Packages/src/Cli~/src/tests/cli-e2e.test.ts:316-323
Subcommands and Options
| Command | Target | Scope | Description |
|---|---|---|---|
list | --claude, --codex | -g, --global | Lists all bundled and project skills and their installation status for the specified targets and scope. |
install | --claude, --codex | -g, --global | Installs or updates all available skills to the target's skill directory (e.g., .claude/skills/). |
uninstall | --claude, --codex | -g, --global | Removes all uloop skills from the target's skill directory. |
- Target: Specifies the AI tool (e.g., Claude Code, Codex). If no target is specified for
list, it shows all. Forinstall/uninstall, a target is required. - Scope:
--globalinstalls to a user-level directory (e.g.,~/.claude/skills), while the default is a project-level directory (.claude/skills/).
Sources: Packages/src/Cli~/src/skills/skills-command.ts:23-60
Conclusion
The uloop CLI and its associated Skills system provide a robust and flexible bridge between LLM-based development tools and the Unity Editor. By decoupling command definitions from the CLI binary and using a dynamic sync mechanism, it ensures that the command set remains current with the tools available in Unity. The Skills system further enhances this by making these commands discoverable and usable by AI agents, enabling powerful, automated development workflows with minimal setup and no need for MCP server configuration.
Sources: README.md, Packages/src/Cli~/src/cli.ts