# Add Config

> Add config to this macOS dotfiles repo. Use for env vars, fish abbreviations/functions/plugins, direct symlinked config files, tool integrations, shared agent config, and app config such as Neovim, Ghostty, Git, Bat, Atuin, tealdeer, and gh.

- Skill: `nwiizo/add-config` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nwiizo/add-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nwiizo/add-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nwiizo (https://skillmd.com/u/nwiizo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nwiizo/add-config

---


# add-config

Add or update dotfiles config in the repo source. Target files under
`~/.config` and `~/.local/bin` are generated by symlinks; do not
edit them directly.

## Route

Start with the area reference, then read only the relevant README section when
repository behavior or commands need clarification:

| Area | Read |
|---|---|
| Fish | [references/fish.md](references/fish.md), then the relevant section of `fish/README.md` |
| Neovim / LazyVim | [references/neovim.md](references/neovim.md), then the relevant section of `nvim/README.md` |
| Shared agent config | `.agents/rules/authoring.md`, then the relevant section of `.agents/README.md` |
| Other apps | the app README when present, then its source config and checks |

## File Map

| Concern | Edit |
|---|---|
| Fish env vars, abbreviations, interactive integrations | `fish/config.fish` |
| Fish plugins | `fish/fish_plugins` |
| Fish functions | `fish/functions/*.fish` |
| Fish early PATH, startup snippets, vendor overrides | `fish/conf.d/*.fish` |
| Neovim plugins/options/keymaps | `nvim/lua/...` |
| Ghostty | `ghostty/config` |
| Git/GitHub config | `git/config`, `gh/config.yml` |
| Bat/Atuin/tealdeer | `bat/config`, `atuin/config.toml`, `tealdeer/config.toml` |
| Shared agent config | `.agents/agents/`, `.agents/rules/`, `.agents/docs/`, `.agents/skills/` |
| Bootstrap/link behavior | `scripts/bootstrap.sh`, `scripts/link.sh` |
| Packages | `Brewfile` via `add-package` |

## Workflow

1. Inspect the repo source, its link rule, and the current tool version.
2. Put the change in the mapped source file and follow the area reference.
3. Preserve grouped style. Keep guarded behavior behind short/default aliases;
   use explicit names for permission bypasses or destructive modes.
4. Keep app reload work separate from package installation. Validate effective
   behavior when a parser accepts obsolete or ignored settings.
5. Existing linked-file edits need no relinking. Reload the owning app as needed
   and distinguish a saved setting from behavior verified in the app; report
   settings that only affect new sessions, tabs, or windows. When adding or
   removing a path, inspect whether its parent is linked, update `scripts/link.sh`
   only if needed, then run it.
6. Use `add-package` when a binary must also be added to `Brewfile`.
7. Keep caches, histories, generated state, credentials, and local overrides
   outside the repository.

## Validation

For Fish or Neovim, run the commands in its selected reference. For another
app, run its README or source-adjacent checks and a targeted smoke test.
Additionally:

- Package change: `brew bundle check --file Brewfile`
- Agent asset change: `./scripts/audit-agent-config.sh`
- Fish plugin change: `fish scripts/install-fish-plugins.fish`

## Don't

- Do not edit `archive/` unless the user explicitly asks.
- Do not edit generated target files directly.
- Do not symlink writable cache/state directories unless the tool expects it.
- Do not replace a standard command with a function unless its CLI is fully
  compatible; prefer a distinct name or an interactive abbreviation.
- Do not reformat or refactor unrelated config.