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

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, 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, this utility mimics what useradd -m does for fresh accounts, but applies it to existing users.

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

# 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.
• 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.
• System updates may modify /etc/skel through migrations like 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 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.

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