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

> Omarchy seeds new users' home directories using /etc/skel. Discover how the omarchy-settings package automatically configures new user environments for a seamless setup.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-03

---

**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](https://github.com/omacom/omarchy/blob/quattro/docs/file-layout.md#L35).

Files are mapped from source directories into the skeleton structure [docs/file-layout.md#L84-L88](https://github.com/omacom/omarchy/blob/quattro/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.

```bash

# 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](https://github.com/omacom/omarchy/blob/quattro/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](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-reinstall-configs#L14-L19):

```bash

# 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](https://github.com/omacom/omarchy/blob/quattro/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](https://github.com/omacom/omarchy/blob/quattro/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.