The Role of /etc/skel/ in Omarchy User Creation

In Omarchy, /etc/skel/ serves as the seed directory that provides default configuration files, desktop entries, and scripts to every new user during account creation.

The Omarchy distribution leverages the standard Linux /etc/skel/ mechanism to establish a consistent baseline environment across all user accounts. When administrators create new users, the system copies the entire contents of this skeleton directory into the freshly created home folder, ensuring that window manager configurations, shell profiles, and application launchers are present from the first login.

How Omarchy Seeds New User Environments

Omarchy treats /etc/skel/ as the single source of truth for static user defaults. The workflow separates static seed files from dynamic configuration, allowing the distribution to enforce consistency while preserving user autonomy after initial setup.

The Initial Seed Phase

The omarchy-settings package installs Omarchy's default dotfiles and directory structures directly into /etc/skel/ during system installation. According to docs/file-layout.md, these files include Hyprland window manager configurations, Bash profiles, and XDG-compliant directory layouts that define the baseline user experience.

This seeding approach ensures that any user created via standard Linux tools receives an identical starting environment. The static files remain under system control, while subsequent per-user modifications happen in the home directory after the copy operation completes.

Automatic Copying During User Creation

When the system creates a new user account with the -m flag (e.g., useradd -m username), the useradd utility automatically copies the entire /etc/skel/ tree into the new $HOME directory. As documented in docs/file-layout.md lines 333-336, this behavior provides every user with a ready-to-use configuration set without requiring manual intervention or post-creation scripts for basic file placement.

Post-Creation Configuration Management

While /etc/skel/ handles static file distribution, Omarchy implements a two-phase approach where runtime modifications occur after the initial seed copy.

Runtime Finalization with omarchy-provision-user

After the skeleton files are in place, bin/omarchy-provision-user executes per-user finalization steps that cannot be stored in /etc/skel/ itself. As implemented in lines 12-16 of the source, this script creates skill symlinks, updates XDG directory variables, and performs other dynamic configurations that must reflect the current system state rather than static defaults.

# Provision a newly created user (run after the seed is in place)

omarchy-provision-user

# This runs the per-user steps that cannot be seeded via /etc/skel/

Restoring Factory Defaults via omarchy-reinstall-configs

Existing users can revert to the original Omarchy defaults by running bin/omarchy-reinstall-configs. This script destructively overwrites the current home directory with a fresh copy of /etc/skel/, effectively resetting configurations to the distribution standard. Lines 14-19 of the source reveal that this is implemented as a force copy operation: cp -af /etc/skel/. ~/.

# Re-install the default configs for the current user

omarchy-reinstall-configs

# This runs: cp -af /etc/skel/. ~/

Maintaining Defaults Across System Updates

Omarchy's skeleton directory is not static; it evolves with the distribution through structured migration pathways.

Migration Scripts for New Skeleton Files

When Omarchy updates introduce new default configurations, migration scripts ensure these additions land in /etc/skel/ for future users. For example, migrations/1781485962.sh (lines 17-18) creates new paths within the skeleton directory, ensuring that users created after the migration receive the updated file set without affecting existing home directories.

Nix Deployment Policies for Immutable Defaults

In Omarchy's Nix-based deployment plans, the seeding step is declared non-negotiable. According to plans/nix.md lines 80-82, the policy mandates that ~/.config remains under user control while /etc/skel/ stays the only automatic source of defaults. This architectural decision prevents configuration drift in immutable system deployments while still allowing users freedom to customize their runtime environments.

# Inspect what Omarchy ships into /etc/skel

tree /etc/skel

# Typical output includes:

# ├─ .bashrc

# ├─ .config/

# │   ├─ hypr/

# │   └─ omarchy/

# ├─ .local/

# │   ├─ share/

# │   │   └─ applications/

# │   └─ state/

# └─ .profile

Summary

• /etc/skel/ acts as the seed directory containing Omarchy's default user configurations, copied automatically when creating new accounts via useradd -m.
• The omarchy-settings package populates this directory with static defaults including window manager configs and shell profiles.
• bin/omarchy-provision-user handles runtime customizations that cannot be pre-seeded, such as skill symlinks and XDG directory updates.
• bin/omarchy-reinstall-configs allows existing users to restore factory defaults by force-copying /etc/skel/ back into their home directory.
• Migration scripts like migrations/1781485962.sh update the skeleton directory for future user creation without altering existing setups.
• Nix-based deployments enforce strict separation between system-managed skeleton files and user-controlled ~/.config directories.

Frequently Asked Questions

What files does Omarchy place in /etc/skel/?

Omarchy ships window manager configurations (Hyprland), Bash and shell profiles, desktop entries, icons, and XDG directory structures into /etc/skel/. These include .bashrc, .config/hypr/, .local/share/applications/, and .profile, creating a complete desktop environment upon first login.

How can I restore default configurations if I break my user setup?

Run the omarchy-reinstall-configs command. This utility force-copies the current contents of /etc/skel/ into your home directory, overwriting any broken or modified configurations with the distribution defaults. Note that this operation is destructive and will replace any personal customizations made to files present in the skeleton directory.

Why does Omarchy separate skeleton files from runtime user provisioning?

Omarchy separates static files in /etc/skel/ from runtime provisioning to maintain a clean architectural boundary between distribution defaults and system-specific configurations. Files in /etc/skel/ cannot contain environment-specific paths or dynamically generated symlinks, so omarchy-provision-user executes after account creation to handle these variable elements while keeping the skeleton directory portable and reproducible.

Does modifying /etc/skel/ affect existing users?

No. Changes to /etc/skel/ only impact users created after the modification. Existing home directories retain the files copied at creation time. To update existing users with new defaults, administrators must either manually copy files or instruct users to run omarchy-reinstall-configs, which explicitly pulls the current skeleton state into existing home directories.

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