# Understanding the Role of /etc/skel in Omarchy User Setup

> Discover how the /etc/skel directory in Omarchy seeds new user accounts with essential dotfiles and XDG configurations, streamlining user setup and personalization.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The `/etc/skel` directory serves as the skeleton template that automatically seeds new Omarchy user accounts with default dotfiles, desktop entries, and XDG configuration files during account creation.**

In the Omarchy Linux distribution (maintained by Basecamp), the `/etc/skel` directory plays a critical role in standardizing user environments from the moment accounts are created. According to the Omarchy source code, this skeleton mechanism ensures every new user receives identical baseline configurations without manual intervention, while runtime provisioning scripts handle path-dependent customizations afterward.

## What Is /etc/skel and How Omarchy Uses It

On Linux systems, `/etc/skel` (short for "skeleton") is the directory that the `useradd -m` command copies into a newly created user's home directory. Omarchy leverages this standard Unix mechanism to distribute its default configuration files system-wide.

As documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), the `omarchy-settings` package installs static defaults—including dotfiles, desktop entries, and XDG directories—directly into `/etc/skel`. When an administrator creates a user account with `useradd -m`, these files automatically populate the new home directory with Omarchy's curated defaults.

## Seeding New Users with omarchy-settings

The Omarchy settings package handles the initial population of the skeleton directory. This approach ensures that system-wide defaults remain immutable on disk while being freely copyable to new accounts.

Key aspects of this seeding process include:

- **Static Configuration Files**: Dotfiles and desktop entries that do not depend on runtime variables reside in `/etc/skel` for automatic distribution.

- **XDG Directory Structure**: Standardized locations for user-specific data and configuration are pre-established in the skeleton to ensure compliance with XDG specifications.

- **Package-Managed Defaults**: Updates to the `omarchy-settings` package modify `/etc/skel` for future users without affecting existing home directories.

## Runtime Provisioning Beyond the Skeleton

Not all configuration steps can occur during the skeleton copy phase. Files that depend on environment variables like `$OMARCHY_PATH` or require user-specific symlinks cannot be templated in `/etc/skel` because they would retain skeleton-relative paths rather than user-specific ones.

After the initial skeleton copy, Omarchy executes **`omarchy-provision-user`** to complete per-user setup. As implemented in `bin/omarchy-provision-user`, this script handles:

- Creating **skill symlinks** that reference the user's specific Omarchy installation path.
- Establishing runtime-dependent XDG directories that require absolute paths.
- Configuring mime defaults that must point to user-specific locations.

## Re-syncing Existing Homes with omarchy-reinstall-configs

When defaults change or configurations drift, administrators may need to reset a user's home directory to the current skeleton state. The **`omarchy-reinstall-configs`** command—implemented in `bin/omarchy-reinstall-configs`—destructively copies the current `/etc/skel` tree over the user's existing home directory.

As noted in [`plans/dots.md`](https://github.com/basecamp/omarchy/blob/main/plans/dots.md), this utility mimics what `useradd -m` does for fresh accounts, but applies it to existing users.

```bash

# Re-apply the current skeleton to an existing user (destructive!)

omarchy-reinstall-configs

```

## Migration Support and Skeleton Updates

Omarchy migration scripts occasionally modify `/etc/skel` to introduce new default files for future users. For example, [`migrations/1781485962.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1781485962.sh) writes Hyprland configuration entries into the skeleton directory to ensure new users receive updated window manager defaults without affecting existing installations.

This migration pattern ensures that:

1. New users automatically receive the latest configurations upon account creation.
2. Existing users remain unaffected unless they manually re-sync.
3. System administrators can track configuration evolution through versioned migration scripts.

## Practical Examples

The following commands demonstrate the complete Omarchy user setup workflow, from skeleton installation to runtime provisioning:

```bash

# The omarchy-settings package populates /etc/skel automatically.

# After installation, /etc/skel contains Omarchy's dotfiles.

# Create a new user - the skeleton copies automatically to /home/newuser

sudo useradd -m -G wheel newuser

# Finish per-user runtime setup (creates skill symlinks, XDG dirs, etc.)

omarchy-provision-user

# Reset an existing user's config to skeleton defaults (destructive!)

omarchy-reinstall-configs

```

## Summary

- **`/etc/skel`** serves as the immutable source of seed files for new Omarchy users, populated by the `omarchy-settings` package according to [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md).
- **New user creation** leverages standard Linux `useradd -m` behavior to copy skeleton files into home directories automatically.
- **Runtime configuration** occurs via `omarchy-provision-user`, which handles path-dependent setup that cannot reside in the static skeleton directory.
- **Configuration resets** use `omarchy-reinstall-configs` to destructively overlay current skeleton defaults onto existing homes, as documented in [`plans/dots.md`](https://github.com/basecamp/omarchy/blob/main/plans/dots.md).
- **System updates** may modify `/etc/skel` through migrations like [`migrations/1781485962.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1781485962.sh) to update defaults for future users only.

## Frequently Asked Questions

### What happens to existing files when I run omarchy-reinstall-configs?

The `omarchy-reinstall-configs` command, as implemented in `bin/omarchy-reinstall-configs`, destructively copies the entire `/etc/skel` directory tree over the user's home directory. This operation overwrites any existing files with identical names, effectively resetting the user's environment to system defaults.

### Why doesn't Omarchy put skill symlinks in /etc/skel?

Symlinks placed in `/etc/skel` would contain absolute paths tied to the skeleton directory itself rather than the user's actual home path. Since skill symlinks must reference specific locations within `$OMARCHY_PATH` relative to the user's environment, Omarchy delegates this task to `omarchy-provision-user`, which establishes correct paths after account creation.

### How do I update default files for future users without affecting current ones?

Update the `omarchy-settings` package or modify files directly in `/etc/skel`. Changes to the skeleton directory only affect users created after the modification. Existing users retain their current configurations unless they voluntarily run `omarchy-reinstall-configs` or administrators manually propagate changes.

### Where does Omarchy document the skeleton directory layout?

The [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) file in the Omarchy repository describes the overall system layout and explicitly details how the `omarchy-settings` package seeds `/etc/skel` for new user creation. This documentation establishes the relationship between package-managed defaults in the skeleton and per-user home directories.