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

> Learn how to install reusable agent skills with orx. This guide shows how the orx install-skills command enables agents to discover and invoke the orx command automatically.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/install_skills.rs)) references the skill definitions found in [`src/local/agent_skills.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/install_skills.rs), displays exactly which files will be written and where before prompting for confirmation.

```bash
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:

```bash

# 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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/install_skills.rs)**: Implements the CLI command, shim generation, `--full` logic, and interactive prompts.
- **[`src/local/harness/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/harness/mod.rs)**: Defines the `Harness` trait with methods `skill_target()`, `skill_shim()`, and `is_installed_locally()`.
- **[`src/local/harness/registry.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/harness/registry.rs)**: Maintains the list of registered harnesses for supported agents.
- **[`src/local/agent_skills.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/local/agent_skills.rs)**: Contains modular skill definitions used when `--full` is specified.
- **[`src/main.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/src/commands/install_skills.rs), utilizing the `Harness` trait defined in [`src/local/harness/mod.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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`](https://github.com/alphaXiv/OpenResearch/blob/main/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.