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

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/ in the repository. Examples include antigravity.sh, 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:

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:

# 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:

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:

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, silently forcing 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:

$ 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:

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:

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:

# 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 — Main provisioning script containing the symlink loop
• install/user/skills/ — Source directory for skill scripts
• 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/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.

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