How to Install Reusable Agent Skills with `orx`: A Complete Guide

The orx install-skills command drops thin shim files into coding agent configuration directories, enabling agents like Claude, Codex, OpenCode, and Cursor to discover and invoke the /orx command automatically.

The orx CLI from the alphaXiv/OpenResearch repository simplifies agent skill installation by detecting your local development environment and writing targeted configuration files. This process integrates orx directly into your coding agents' workflows without manual configuration file editing.

How the orx install-skills Command Works

In src/commands/install_skills.rs, the orx install-skills command implements a multi-step process to inject skill shims—thin configuration files that teach coding agents how to invoke orx—into the appropriate directories.

Detecting Compatible Agent Harnesses

The command first iterates over registered harnesses defined in the broader codebase (see src/local/harness/registry.rs). It selects only those harnesses where skill_target() returns Some, indicating the agent supports shim-based skill injection.

According to the source code in src/commands/install_skills.rs (lines 23-29), this filtering ensures that only actively supported agents—Claude, Codex, OpenCode, and Cursor—are processed.

Agent Targeting and Auto-Detection

The installer determines which agents to target using two distinct modes:

• Specific agent selection: When you pass --agent <name>, the command targets only that agent. The implementation handles name aliases (for example, mapping both claude and claude-code to the same harness) as shown in lines 65-79 of src/commands/install_skills.rs.
• Auto-detection: Without the --agent flag, the command checks is_installed_locally() for each harness to discover which agents are already configured on your machine. If none are found, it defaults to all installable agents (lines 81-93).

Writing Shim Files

For each selected harness, the command:

1. Creates the target directory if it does not exist.
2. Writes the shim content, overwriting any existing file to ensure updates are applied.

This logic appears in lines 31-49 of src/commands/install_skills.rs. The shim files serve as bridges, allowing the agent to recognize and execute the /orx command within its context.

Installing the Full Modular Skill Set

Beyond basic shims, orx supports a full skill installation via the --full flag. When invoked as orx install-skills --full, the CLI writes the entire modular skill collection into the agent's global skills directory.

For example, this installs skills to ~/.claude/skills for Claude or equivalent paths for other agents. The implementation (lines 104-112 of src/commands/install_skills.rs) references the skill definitions found in src/local/agent_skills.rs.

Interactive Installation After Login

After running orx login, the CLI automatically offers to install skills if it detects any configured agents on your machine. This interactive flow, implemented in lines 122-138 of src/commands/install_skills.rs, displays exactly which files will be written and where before prompting for confirmation.

orx login

# ... login succeeds ...

# orx ships one agent skill: a small file teaching your coding agent to run

# `orx skill` for the bundled guide. It can be installed now (1 file) for the

# agent detected on this machine:

#   Opencode → ~/.config/opencode/skills/orx/SKILL.md

# Install? [Y/n] y

# ✓ Installed opencode skill → ~/.config/opencode/skills/orx/SKILL.md

Practical Installation Examples

Here are the common patterns for installing reusable agent skills:

# Install shims for all detected agents (default)

orx install-skills

# Install only for a specific agent

orx install-skills --agent claude     # or `claude-code`

orx install-skills --agent codex
orx install-skills --agent cursor
orx install-skills --agent opencode

# Install shims **and** the full modular skill set

orx install-skills --full

# Combine both flags for targeted full installation

orx install-skills --agent opencode --full

Key Implementation Files

The skill installation system relies on these components in the alphaXiv/OpenResearch repository:

• src/commands/install_skills.rs: Implements the CLI command, shim generation, --full logic, and interactive prompts.
• src/local/harness/mod.rs: Defines the Harness trait with methods skill_target(), skill_shim(), and is_installed_locally().
• src/local/harness/registry.rs: Maintains the list of registered harnesses for supported agents.
• src/local/agent_skills.rs: Contains modular skill definitions used when --full is specified.
• src/main.rs (lines 114-118): Registers install-skills as a top-level command in the CLI.

Summary

• The orx install-skills command injects thin shim files into agent configuration directories, enabling automatic discovery of the /orx command.
• Auto-detection inspects is_installed_locally() to target only agents present on your system, while --agent enables precise targeting with alias support for claude/claude-code.
• The --full flag copies complete modular skill sets from src/local/agent_skills.rs into agent-specific global skill directories like ~/.claude/skills.
• Interactive installation triggers automatically after orx login, showing file paths before confirmation.
• All logic resides in src/commands/install_skills.rs, utilizing the Harness trait defined in src/local/harness/mod.rs.

Frequently Asked Questions

How do I install skills for only one specific agent?

Use the --agent flag followed by the agent name. For example, orx install-skills --agent claude installs only for Claude (also accessible via the claude-code alias). This targeting is handled in lines 65-79 of src/commands/install_skills.rs.

What is the difference between default installation and --full?

The default installation writes only a thin shim file that enables the /orx command recognition. Adding --full also writes the complete modular skill collection from src/local/agent_skills.rs into the agent's global skills directory (e.g., ~/.claude/skills), exposing the full orx functionality set.

Will orx install-skills overwrite existing skill files?

Yes. According to lines 31-49 of src/commands/install_skills.rs, the command creates the target directory if missing and writes the shim content, overwriting any existing file to ensure you have the latest version.

Can I install skills without running orx login first?

Yes. The orx install-skills command operates independently and can run anytime. However, running orx login first enables an interactive prompt that automatically detects installed agents and offers to install skills immediately after authentication.

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