dotfiles

Personal configuration files and environment setup.

Structure

dotfiles/
├── zsh/
│   ├── .zshenv        # Global zsh env (all shell modes)
│   ├── .zshrc         # Interactive shell config
│   └── .zprofile      # Login shell config (PATH, env vars)
├── git/
│   ├── .gitconfig     # Git configuration
│   ├── ignore         # Global ignore rules (→ ~/.config/git/ignore)
│   └── allowed_signers  # SSH signing key for signature verification
├── ssh/
│   └── config         # SSH client config (1Password agent only for local sessions)
├── mise/
│   └── global-config.toml   # mise global config (copied to ~/.config/mise/config.toml)
├── starship/
│   └── starship.toml  # Starship prompt configuration
├── ghostty/
│   └── config         # Ghostty terminal configuration
├── cursor/
│   ├── settings.json    # Cursor editor settings
│   ├── keybindings.json # Cursor keybindings
│   ├── cli-config.json  # Cursor CLI template (attribution merged into ~/.cursor/cli-config.json)
│   └── mcp.json         # MCP server config
├── agents/
│   ├── GLOBAL.md      # Shared AI guidelines + compiled @> skill index block
│   ├── claude.settings.json     # Claude Code settings
│   ├── codex.config.toml        # Codex settings
│   ├── conductor.settings.toml  # Conductor user settings
│   ├── claude.statusline-command.sh
│   ├── hooks/         # Claude Code hooks (e.g. PR guideline check)
│   ├── compile-global.ts        # Annotation compiler
│   ├── .build/       # Generated instructions and skills by harness (gitignored)
│   ├── skills/        # [P] Personal skills (hand-written)
│   │   ├── conductor/       # Conductor worktrees / CONDUCTOR_* / target branch
│   │   ├── pr-guidelines/
│   │   ├── code-quality/
│   │   ├── write/
│   │   ├── skills-manager/
│   │   └── .../
│   └── skills.local/  # [L] Private skills (optional submodule)
├── local/
│   ├── env.template       # Machine-specific env vars template
│   └── secrets.template   # API keys/tokens template
├── git-hooks/
│   └── pre-commit         # Auto-compiles GLOBAL.md annotations
├── .agents/
│   └── skills/        # [E] External skills (from skills.sh)
│       └── .../
├── install.sh         # Symlink installation script
├── setup.sh           # Repo-local setup (git hooks)
├── Brewfile           # Homebrew dependencies
├── skills-lock.json   # External skill version tracking
├── links.txt          # Symlink mappings
├── Makefile           # Common tasks (install, check, etc.)
└── README.md

Installation

make install    # Full install (compile annotations + symlink + sync skills)
make setup      # Repo-local setup (git hooks) — run once per clone/worktree
make link       # Same as install but skip brew/mise dependency install (faster iteration)
make update     # git pull + full install (refresh from remote)

After this repo is on your machine and zsh is sourced, the dotup alias runs make update from ~/Code/dotfiles (see zsh/.zshrc).

make install will:

1. Compile skill annotations and harness inclusion into generated instructions and skill trees
2. Back up any existing files to ~/.dotfiles-backup/
3. Create symlinks from this repo to ~/ (based on links.txt)
4. Copy mise global config and Cursor global.mdc (not symlinked — see install.sh); merge tracked Cursor CLI attribution into ~/.cursor/cli-config.json (not a symlink — Cursor writes auth/model there); symlink ~/AGENTS.md for Cursor CLI ancestor discovery
5. Sync all skills (personal, external, local) to ~/.claude/skills/, ~/.codex/skills/, and ~/.cursor/skills/
6. Register MCP servers with Claude Code (user scope)

make link sets SKIP_DEPENDENCY_INSTALL=1 so Homebrew/mise steps are skipped; use it when deps are already satisfied. make update is for pulling latest dotfiles and re-running a full install.

Usage

Edit symlinked files in this repo; changes apply immediately. Copied/merged files (mise/global-config.toml, Cursor global rules, Cursor CLI attribution) need make link after edits. After pulling:

source ~/.zshrc

Adding New Configs

1. Add the config file to the appropriate directory
2. Add mapping to links.txt
3. Run make link to sync

Managing Skills

Authoring details: agents/skills/README.md.

Skills come in three types:

• [P] Personal — Hand-written, tracked in agents/skills/
• [L] Local — Private skills in the optional agents/skills.local/ submodule
• [E] External — Installed from GitHub via skills.sh in .agents/skills/

make link / install.sh deploy compiled skills to their selected harnesses. Whole-skill metadata and section markers control inclusion, as described in Agent skills. Excluded copies of a current source skill are removed from that target. Removed or renamed source directories still require separate orphan cleanup. After dropping or renaming a skill, remove the stale folder from those home paths too (compare ls agents/skills / .agents/skills / agents/skills.local with ls ~/.claude/skills). See the skills-manager skill (agents/skills/skills-manager/) for the full cleanup checklist.

Private skills

agents/skills.local is an optional submodule backed by the private Aias/dotfiles-local repository. Public clones can run the installer without initializing it. The public repository stores its URL and pinned commit, while skill contents and history remain private.

With access to the private repository, initialize the pinned revision and deploy:

make setup-private-skills

To fetch and deploy the latest private main revision:

make update-private-skills

Updating requires a clean private checkout and uses a fast-forward merge. Divergent history stops the update for review. Regular make install, make link, and make update deploy the private checkout as it stands, without moving its revision.

Private skill edits are committed and pushed inside agents/skills.local first. Then commit the updated submodule reference in dotfiles. Initialization can leave the submodule detached, so create a working branch there before editing. Credentials and authentication state stay outside both repositories.

Adding a Personal Skill

1. Create agents/skills/<skill-name>/SKILL.md
2. Run make link (and make compile if the skill uses global_category + @> annotations)

Adding an External Skill

# Install (downloads to .agents/skills/)
npx skills add OWNER/REPO --skill SKILL-NAME -a claude-code -y

# Remove the symlink it creates (we deploy via make link instead)
rm -f .claude/skills/SKILL-NAME

# Deploy
make link

Updating External Skills

make update-skills

Removing a Skill

1. Delete the skill directory under agents/skills/, agents/skills.local/, or .agents/skills/
2. Remove any matching entry from skills-lock.json (external skills)
3. Delete the same skill name under ~/.claude/skills/, ~/.codex/skills/, and ~/.cursor/skills/ (not done automatically)

Verifying Sync Status

make check

Shows a table of all skills with sync status for each agent:

skill                        type  claude  codex  cursor
changelog                    [P]   ✓       ✓      ✓
react-best-practices         [P]   ✓       ✓      ✓