How Omarchy Seeds New Users' Home Directories Using `/etc/skel`

Omarchy populates /etc/skel with its omarchy-settings package so that every new user automatically receives a preconfigured environment when useradd -m creates their home directory.

Omarchy's file layout leverages the standard Linux skeleton directory mechanism to ensure users start with consistent defaults. This approach eliminates manual setup by shipping dotfiles, application shortcuts, and configuration directories directly into the system-wide template that useradd copies on account creation.

How /etc/skel Seeding Works in Omarchy

The seeding process combines package-based delivery with standard Unix user creation workflows.

Static Defaults Ship via omarchy-settings

The omarchy-settings PKGBUILD installs a complete hierarchy under /etc/skel. According to the file-layout documentation, this package "Seed — omarchy-settings ships static defaults to /etc/skel/" docs/file-layout.md#L35.

Files are mapped from source directories into the skeleton structure docs/file-layout.md#L84-L88:

Source	Destination in /etc/skel
config/**	.config/**
applications/*.desktop	.local/share/applications/

This mapping ensures XDG-compliant directories and desktop entries land in the correct locations for immediate use.

Automatic Application on User Creation

When administrators run useradd -m, the -m flag triggers copying /etc/skel contents into the new user's $HOME. Omarchy relies on this standard behavior—no custom hooks or wrappers are needed for initial seeding.

# Create a new user – home directory is populated from /etc/skel automatically

sudo useradd -m alice

# Verify the seeded files

ls -la /home/alice/.config/

Per-User Finalization Beyond /etc/skel

Some configurations cannot be baked into static skeleton files. Omarchy runs bin/omarchy-finalize-user after the initial copy to handle runtime-dependent setup agents/skills/install-scripts.md#L10-L12:

• Creating XDG user directories (~/Documents, ~/Downloads, etc.)
• Setting up skill symlinks for the Omarchy agent system

This two-phase approach—static skeleton plus dynamic finalization—covers both portable defaults and environment-specific requirements.

Re-seeding Existing Users with Current Defaults

Users created before a configuration update can synchronize with the latest skeleton via bin/omarchy-reinstall-configs. This script force-copies /etc/skel into the running user's home directory bin/omarchy-reinstall-configs#L14-L19:

# Update current user to match latest /etc/skel defaults

omarchy-reinstall-configs

The implementation uses cp -af /etc/skel/. ~/ to preserve hidden files and overwrite existing configurations with the package-shipped versions.

Why Omarchy Uses /etc/skel for User Seeding

Four design advantages drive this architecture:

1. Standards compliance — /etc/skel is the POSIX-defined location for default user files, ensuring compatibility with useradd, adduser, and system management tools.

2. Package atomicity — Shipping skeleton files through omarchy-settings ties versioning to the package manager, enabling rollback and dependency tracking.

3. Zero custom logic for creation — New users require no post-creation scripts; the standard useradd -m workflow suffices.

4. Separation of concerns — Static configs live in /etc/skel, while dynamic, per-user adjustments are delegated to omarchy-finalize-user.

Summary

• omarchy-settings populates /etc/skel with dotfiles, desktop entries, and XDG configurations docs/file-layout.md#L35.
• useradd -m automatically copies skeleton contents to new home directories.
• omarchy-finalize-user applies runtime tweaks that static files cannot provide.
• omarchy-reinstall-configs synchronizes existing users with updated skeleton defaults.

Frequently Asked Questions

What happens if I modify files in /etc/skel after creating a user?

Changes to /etc/skel only affect future user accounts. Existing users retain their originally copied files unless they run omarchy-reinstall-configs to force an update from the current skeleton.

Can I exclude specific skeleton files for certain users?

Standard useradd does not support selective exclusion from /etc/skel. For custom setups, create users without -m and manually copy desired files, or modify omarchy-reinstall-configs to filter specific paths.

Where does Omarchy store the source files before they reach /etc/skel?

The omarchy-settings PKGBUILD contains install directives that place files into $pkgdir/etc/skel/ during package build. These correspond to the config/** and applications/ mappings documented in the file-layout specification docs/file-layout.md#L84-L88.

Does omarchy-reinstall-configs back up existing user files?

No—the script runs cp -af /etc/skel/. ~/ which overwrites existing files without backup. Users should version-control their dotfiles or manually archive configurations before re-seeding if preservation is required.

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