# Dotfiles

> Dotfiles project guidelines (English, minimal config, Makefile for installs)

- Skill: `diegosouzapw/dotfiles` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/dotfiles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/dotfiles/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/dotfiles

---


# Dotfiles Guidelines

- All comments and documentation must be written in **English**
- Keep configurations **simple and minimal** — avoid over-engineering
- **Avoid unnecessary comments** — prefer self-documenting code. Only add comments when they explain *why* something is done, not *what* it does. Configuration option names are usually self-explanatory.
- Primary platform: **macOS** (Darwin), but keep configs **portable to Linux** (EC2, servers)
- Avoid macOS-specific features when a cross-platform alternative exists
- Use `uname` or similar checks when platform-specific code is unavoidable

## Installation & Package Management

**CRITICAL**: Always use the Makefile for installing tools and applications. Never install packages directly with `brew install`, `npm install -g`, or other package managers. See `makefile.md` for details.

## Symlink Conventions

Configuration files are symlinked from this repo:

- `~/.config/fish` → `~/.dotfiles/fish`
- `~/.config/nvim` → `~/.dotfiles/nvim`
- `~/.config/Cursor/User/*` → `~/.dotfiles/cursor/*`

Always update the Makefile when adding new symlinked configurations.

## Code Style

### Comments
- **Minimal comments**: Only comment when explaining non-obvious behavior or important context
- **No obvious comments**: Don't comment what the code already clearly shows (e.g., `scrollback_lines = 200000` doesn't need a comment)
- **Self-documenting**: Prefer clear variable/option names over comments
- **When to comment**: Only when explaining *why* something is configured a certain way, not *what* it does

## Primary Work Context

Main technologies used daily:

- **TypeScript** — Use strict mode, prefer explicit types
- **PostgreSQL** — Use UPPER CASE for SQL keywords
- **Node.js** — Managed via Volta