# How `omarchy-provision-user` Sets Up Skill Symlinks: Complete Walkthrough

> Discover how omarchy-provision-user sets up skill symlinks in your home directory, granting direct access to Omarchy helper commands without file copying or path changes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-06

---

**`omarchy-provision-user` creates executable symlinks in `$HOME/.local/bin` that point to skill scripts inside the Omarchy repository, giving users instant access to helper commands without copying files or modifying system paths.**

The `omarchy-provision-user` script is Omarchy's per-user finalization mechanism. It installs **skills** — small, purpose-built helper scripts — as symlinks rather than copies, ensuring users always run the latest version while keeping the repository as the single source of truth. Let's examine exactly how this works under the hood.

## What Are Omarchy Skills?

Skills in Omarchy are standalone Bash scripts stored in `install/user/skills/`. Each skill provides a specific capability, from SSH management to notification handling. Rather than installing these scripts directly into user directories, Omarchy symlinks them — this design keeps skills updatable and avoids stale copies across the system.

The skills directory lives at [`install/user/skills/`](https://github.com/omacom/omarchy/blob/quattro/install/user/skills/) in the repository. Examples include [`antigravity.sh`](https://github.com/omacom/omarchy/blob/main/antigravity.sh), [`hermes.sh`](https://github.com/omacom/omarchy/blob/main/hermes.sh), and other utilities that extend the Omarchy environment.

## How `omarchy-provision-user` Creates Skill Symlinks

The symlink creation process follows a predictable, idempotent pattern. Here is the complete workflow as implemented in [`bin/omarchy-provision-user`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user):

### 1. Locate Repository and Skill Scripts

The script first establishes `$OMARCHY_PATH` — the root of the Omarchy installation. It then scans the skills directory for executable shell scripts:

```bash

# OMARCHY_PATH is typically /opt/omarchy or /usr/local/omarchy

for skill in "$OMARCHY_PATH"/install/user/skills/*.sh; do
    [ -f "$skill" ] || continue
    # Process each skill script...

done

```

This glob pattern ensures only `.sh` files are considered, with an explicit existence check to handle empty directories gracefully.

### 2. Ensure Target Directory Exists

Before creating any symlinks, the script guarantees that `$HOME/.local/bin` is available in the user's path:

```bash
mkdir -p "$HOME/.local/bin"

```

The `-p` flag prevents errors if the directory already exists and creates parent directories as needed.

### 3. Generate Prefixed Symlinks with `ln -sf`

For each skill script, `omarchy-provision-user` constructs a symlink name prefixed with `omarchy-` to avoid namespace collisions. The core symlink creation uses:

```bash
name=$(basename "$skill" .sh)
ln -sf "$skill" "$HOME/.local/bin/omarchy-$name"

```

Key details of this implementation:

- **`basename "$skill" .sh`** — Strips the path and `.sh` extension, yielding the clean skill identifier
- **`ln -sf`** — Creates the symlink, **s**ilently **f**orcing replacement if a link already exists (enables idempotent re-runs)
- **`omarchy-$name`** — The prefixed naming convention prevents conflicts with system commands

The resulting symlink structure looks like:

```bash
$ ls -l ~/.local/bin/omarchy-*
lrwxrwxrwx 1 user user 42 Jan 15 09:23 /home/user/.local/bin/omarchy-antigravity -> /usr/local/omarchy/install/user/skills/antigravity.sh
lrwxrwxrwx 1 user user 40 Jan 15 09:23 /home/user/.local/bin/omarchy-hermes -> /usr/local/omarchy/install/user/skills/hermes.sh

```

### 4. Track Provisioning State

After successful symlink creation, the script marks the skill as provisioned by touching a state file:

```bash
mkdir -p "$HOME/.local/state/omarchy/provisioned"
touch "$HOME/.local/state/omarchy/provisioned/$name"

```

These marker files enable **incremental provisioning** — subsequent runs skip already-provisioned skills unless `--force` is specified.

## Safety Mechanisms and Flags

The `omarchy-provision-user` script implements several safeguards:

| Flag | Behavior |
|------|----------|
| `--force` | Re-creates symlinks even if state markers exist |
| `--first-install` | Indicates initial provisioning; performs additional setup steps |
| *(default)* | Skips skills with existing state markers |

The script also validates execution context:

```bash
if [ "$(id -u)" -eq 0 ]; then
    echo "Error: omarchy-provision-user must run as the target user, not root" >&2
    exit 1
fi

```

Execution with `set -euo pipefail` ensures the script exits on errors, undefined variables, or pipeline failures.

## Complete Working Example

Here's how to verify and interact with the skill symlink system:

```bash

# Run provisioning for the current user

omarchy-provision-user --force --first-install

# List all available omarchy skills

ls ~/.local/bin/omarchy-*

# Execute a skill directly (now in PATH if ~/.local/bin is configured)

omarchy-antigravity --help

# Check which skills are provisioned

ls ~/.local/state/omarchy/provisioned/

# Add a custom skill and re-provision

cat > /usr/local/omarchy/install/user/skills/my-skill.sh <<'EOF'
#!/usr/bin/env bash
echo "Custom skill output: $*"
EOF
chmod +x /usr/local/omarchy/install/user/skills/my-skill.sh

# Refresh symlinks to pick up the new skill

omarchy-provision-user

# Verify the new symlink exists

ls -la ~/.local/bin/omarchy-my-skill

```

## Key Source Files and Their Roles

- **[`bin/omarchy-provision-user`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-user)** — Main provisioning script containing the symlink loop
- **[`install/user/skills/`](https://github.com/omacom/omarchy/tree/quattro/install/user/skills)** — Source directory for skill scripts
- **[`bin/omarchy-provision-owner`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-provision-owner)** — Higher-level script that invokes `omarchy-provision-user` during system-wide setup
- **[[`test/shell.d/provision-user-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/provision-user-test.sh)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/provision-user-test.sh)** — Automated tests verifying correct symlink behavior

## Summary

The `omarchy-provision-user` tool establishes skill symlinks through a clean, reproducible process:

- Scans `install/user/skills/*.sh` for available skills
- Creates `$HOME/.local/bin` if absent
- Builds `omarchy-<skill>` symlinks pointing to repository scripts using `ln -sf`
- Tracks provisioned state in `$HOME/.local/state/omarchy/provisioned/`
- Supports `--force` and `--first-install` flags for flexible re-provisioning

This symlink-based approach eliminates file duplication, ensures users always execute current skill versions, and maintains clean separation between the system repository and user environments.

## Frequently Asked Questions

### Where are skill symlinks created on my system?

Symlinks are placed in `$HOME/.local/bin/` with the naming pattern `omarchy-<skillname>`. This location is typically already in the user's PATH on most modern Linux distributions, making skills immediately executable without additional configuration.

### What happens if I run `omarchy-provision-user` multiple times?

The script is **idempotent**. Subsequent runs skip skills that have already been provisioned (based on state markers in `~/.local/state/omarchy/provisioned/`). Use the `--force` flag to recreate symlinks regardless of previous runs.

### Can I add my own custom skills to Omarchy?

Yes. Create a new `.sh` file in `$OMARCHY_PATH/install/user/skills/` with executable permissions and a proper shebang. Running `omarchy-provision-user` will automatically create the corresponding symlink. No modification to the provisioning script itself is required.

### Why does Omarchy use symlinks instead of copying skill scripts?

Symlinks ensure **single source of truth**: when the repository updates, users immediately access new skill versions without re-provisioning. This approach also reduces disk usage and eliminates version drift between copies across multiple user accounts.