Dotfiles Repository Assistant

This skill provides expert guidance for working with modern, modular dotfiles repositories that support cross-platform shell environment configuration and development tool installation.

What This Skill Does

Assists with developing, testing, and maintaining a modular dotfiles system that:

Architecture Overview

The repository uses a modular architecture with these core components:

**bin/dotfiles** - Main CLI entry point for commands (install, update, uninstall, doctor, list, status)

**bin/lib/core.sh** - Core library with platform detection, logging, file operations, state management, and shell integration

**bin/lib/module.sh** - Module discovery, validation, and lifecycle management

**bin/lib/doctor.sh** - Health check framework with validation and auto-fix capabilities

**modules/<name>/** - Self-contained modules with install.sh, check.sh, uninstall.sh, module.conf

**shell/{bash,zsh}/** - Shell initialization and module configuration directories

Instructions

1. Understanding the Codebase

When first examining the repository:

2. Adding a New Module

Follow this precise sequence:

**Step 1: Create module directory**

```bash

mkdir -p modules/<modulename>

```

**Step 2: Create module.conf**

```bash

NAME="modulename"

DESCRIPTION="Brief description"

VERSION="auto"

DEPENDENCIES=() # e.g., ("fonts") if depends on other modules

PLATFORMS="linux macos" # or just "linux" or "macos"

SHELLS="bash zsh"

```

**Step 3: Create install.sh**

```bash

#!/usr/bin/env bash

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

source "${SCRIPT_DIR}/../../bin/lib/core.sh"

install_modulename() {

log_step "Installing ${NAME}..."

# Platform-specific installation

case "${DOTFILES_OS}" in

linux)

# Linux installation logic

;;

macos)

# macOS installation logic

;;

esac

# Optional: Create shell integration

create_shell_module "modulename" "export VAR=\"value\""

mark_installed "modulename" "${version}"

log_success "${NAME} installed successfully"

}

install_modulename "$@"

```

**Step 4: Create check.sh**

```bash

#!/usr/bin/env bash

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

source "${SCRIPT_DIR}/../../bin/lib/core.sh"

source "${SCRIPT_DIR}/../../bin/lib/doctor.sh"

check_modulename() {

doctor_check_command "binaryname"

doctor_check_file "${HOME}/.config/modulename/config"

doctor_check_env_var "MODULE_VAR"

return 0

}

check_modulename "$@"

```

**Step 5: Create uninstall.sh**

```bash

#!/usr/bin/env bash

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

source "${SCRIPT_DIR}/../../bin/lib/core.sh"

uninstall_modulename() {

log_step "Uninstalling ${NAME}..."

remove_shell_module "modulename"

# Remove installed files

mark_uninstalled "modulename"

log_success "${NAME} uninstalled successfully"

}

uninstall_modulename "$@"

```

**Step 6: Test in Docker**

```bash

make test-docker

```

3. Platform-Specific Considerations

**Detect platform:**

```bash

case "${DOTFILES_OS}" in

linux)

# Linux-specific

;;

macos)

# macOS-specific

;;

esac

```

**Common platform-specific paths:**

**WSL detection:**

```bash

if [[ "${DOTFILES_ENV}" == "wsl" ]]; then

# WSL-specific logic

fi

```

4. Using Core Library Functions

**Logging:**

**Command checking:**

**File operations:**

**Shell integration:**

```bash

create_shell_module "modulename" "

export VAR=\"value\"

export PATH=\"\${HOME}/bin:\${PATH}\"

"

```

**State management:**

5. Doctor Checks

Use these functions in check.sh:

The doctor command supports `--fix` flag to automatically repair issues:

```bash

dotfiles doctor # Report issues

dotfiles doctor --fix # Auto-fix issues

```

6. Testing Workflow

**Local testing (careful - modifies your system):**

```bash

make setup # First-time setup

make install # Install default modules

make doctor # Health check

./bin/dotfiles --debug install modulename # Debug single module

```

**Docker testing (safe, isolated):**

```bash

make test-docker # Full install test in container

make test-shell # Interactive shell in container

make test-build # Rebuild Docker images

make test-clean # Clean up Docker artifacts

```

**Always test in Docker first** before testing on host system.

7. Installation Behavior

Understand the install command flags:

This makes `dotfiles install` idempotent and safe to run multiple times.

8. Git Practices

**CRITICAL:**

9. Common Patterns

**Download and extract:**

```bash

local url="https://example.com/file.tar.gz"

local dest="${HOME}/bin/binary"

download_file "${url}" "/tmp/download.tar.gz"

tar -xzf "/tmp/download.tar.gz" -C "${HOME}/bin"

```

**Version detection:**

```bash

local version

version=$(curl -sL https://api.example.com/version | grep -oP 'v\K[0-9.]+')

log_info "Latest version: ${version}"

```

**Conditional installation:**

```bash

if is_installed "modulename"; then

log_info "Already installed, skipping..."

return 0

fi

```

10. Module Dependencies

If a module depends on another:

```bash

In module.conf

DEPENDENCIES=("fonts" "git")

The system automatically installs dependencies first

```

11. Shell Integration Details

Modules create shell configs in `shell/{bash,zsh}/modules.d/`:

User customizations go in `~/.local/.dotfiles.d/*.sh` (automatically loaded, not in repo).

12. Troubleshooting

**Module not installing:**

**Doctor checks failing:**

**Shell integration not working:**

Examples

**Example 1: Adding a simple tool module**

```bash

modules/mytool/module.conf

NAME="mytools"

VERSION="1.0.0"

PLATFORMS="linux macos"

modules/mytools/install.sh

install_mytools() {

log_step "Installing mytools..."

case "${DOTFILES_OS}" in

linux)

curl -sL https://example.com/tool > ~/bin/tool

chmod +x ~/bin/tool

;;

macos)

brew install tool

;;

esac

mark_installed "mytools" "1.0.0"

log_success "mytools installed"

}

```

**Example 2: Module with shell integration**

```bash

install_mytool() {

log_step "Installing mytool..."

# Install binary

local version="2.0.0"

download_file "https://example.com/mytool" "${HOME}/bin/mytool"

chmod +x "${HOME}/bin/mytool"

# Create shell integration

create_shell_module "mytool" "

export MYTOOL_HOME=\"\${HOME}/.mytool\"

export PATH=\"\${MYTOOL_HOME}/bin:\${PATH}\"

alias mt='mytool'

"

mark_installed "mytool" "${version}"

log_success "mytool ${version} installed"

}

```

**Example 3: Doctor check with file sync**

```bash

check_mymodule() {

doctor_check_command "mybin"

doctor_check_file "${HOME}/.config/mymodule/config.yml"

doctor_check_file_sync \

"${DOTFILES_REPO}/config/myconfig" \

"${HOME}/.dotfiles/config/myconfig" \

"myconfig"

return 0

}

```

Important Notes