<!-- skill: Vim Mastery | version: 1.0.0 | description: Motions, text-objects, macros, registers, buffers and sane vimrc | category: System & Productivity -->
## Instructions
- Stay in Normal mode by default; Insert only to type, Visual only to select. Esc or `Ctrl-[` to exit, `i/a/o` to enter smartly (`o` opens line below, `O` above).
- Core motions: `w/b/e` words, `0/^/$` line bounds, `gg/G` file bounds, `f/t/F/T + char` line jump, `{/}` paragraph, `%` bracket match, `Ctrl-d/Ctrl-u` half-page.
- Text-objects are the superpower: `ciw` change word, `ca"` change quoted incl quotes, `di(` delete in parens, `yip` yank paragraph, `vat` select tag block. Pattern: verb + i/a + object.
- Operators compose: `d/c/y` + motion/object, `>` indent, `gu/gU` case, `.` repeats last change. `dd/yy/cc` whole-line forms.
- Registers: `"ayy` yank line to a, `"ap` paste a, `"+y` system clipboard (needs +clipboard), `:reg` inspect. Black hole `"_d` deletes without clobbering yank.
- Macros: `qa` record to a, do edits, `q` stop, `@a` replay, `@@` repeat, `10@a` ten times. Use for repetitive refactors across lines.
- Buffers not tabs for files: `:ls`, `:b <n/name>`, `:bn/:bp`, `:bd` close. Splits: `Ctrl-w s/v`, `Ctrl-w h/j/k/l` move, `Ctrl-w =` equalize. Arglist `:args` for project-wide macro replay.
- Search/replace: `/pattern` + `n/N`, `*` word under cursor, `:%s/old/new/gc` confirm each, `:g/pattern/d` delete matches. `:noh` clears highlight.
- .vimrc essentials: `set nocompatible`, `syntax on`, `set number relativenumber`, `set expandtab tabstop=2 shiftwidth=2`, `set ignorecase smartcase`, `set undofile`, `set clipboard=unnamedplus`, `let mapleader=" "`.
- Plugin managers: vim-plug (`call plug#begin()`, `Plug 'tpope/vim-surround'`, `:PlugInstall`) — keep under 10 plugins; LSP via coc.nvim or native neovim path only if needed.
- Save/quit discipline: `:w`, `:q`, `:wq`, `:q!` discard, `:up` save-if-changed. Never `c-z` suspend blindly on remote boxes.
- Marks/jumps: `ma` set mark a, `'a` jump to line, `` `a `` exact column, `Ctrl-o/Ctrl-i` jump history. Global marks (A-Z) span files.
## Examples
- Rename variable in parens: `ci(` then type new name, `.` on next occurrence if same shape.
- Wrap word in quotes: `ysiw"` (vim-surround) or `ciw""<Esc>P`.
- Bulk edit 20 lines: `qa` → `0f:dwj` → `q` → `19@a`.
- Clipboard copy to OS: `"+yy` line, `"+p` paste from OS.
- Replace foo→bar whole file with review: `:%s/\<foo\>/bar/gc`.
## Workflows
1. Open: `vim file` → navigate Normal mode → edit with objects → save.
2. Multi-file: `:e file2` → `:ls` → `:bn/:bp` cycle → `:bd` when done.
3. Macro refactor: record once on line 1 → replay with count → verify with `:w` + git diff.
4. New machine: drop .vimrc → `:PlugInstall` → `:checkhealth` (neovim) → test clipboard.
5. Stuck: `:help <topic>`, `:Tutor` for 30-min refresher.
## Templates
```vim
" ~/.vimrc — minimal sane base
set nocompatible | syntax on | filetype plugin indent on
set number relativenumber cursorline
set expandtab tabstop=2 shiftwidth=2 smartindent
set ignorecase smartcase hlsearch incsearch
set undofile undodir=~/.vim/undodir | set backupdir=~/.vim/backup
set clipboard=unnamedplus | set mouse=a
let mapleader=" "
nnoremap <leader>w :up<CR>
nnoremap <leader>q :q<CR>
nnoremap <leader>h :noh<CR>
nnoremap <C-h> <C-w>h | nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k | nnoremap <C-l> <C-w>l
```
```vim
" vim-plug block (~/.vimrc)
call plug#begin('~/.vim/plugged')
Plug 'tpope/vim-surround'
Plug 'tpope/vim-commentary'
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
Plug 'airblade/vim-gitgutter'
call plug#end()
" :source % then :PlugInstall
```
- Leader shortcuts: `<leader>f` → `:Files<CR>`, `<leader>g` → `:Rg<CR>`, `<leader>b` → `:Buffers<CR>` (fzf.vim).
- Macro starter: `qa0f,dt;jq` — adapt delimiter per file, count = lines-1.
## Tools
- vim 8.2+ / neovim 0.9+, `vim --version` check `+clipboard`; fzf + ripgrep for `:Files`/`:Rg`.
- vim-plug from https://github.com/junegunn/vim-plug; `:Tutor` built-in trainer.
## Advanced
- `:%normal @a` runs macro a on every line; `:g/pattern/normal @a` only on matches — faster than counts.
- `Ctrl-v` block-visual for column edits (`I` insert, `A` append, then Esc applies to all).
- Folds: `zf` create, `zo/zc/za` open/close/toggle, `set foldmethod=indent` for Python/YAML.
- Sessions: `:mksession! ~/proj.vim` then `vim -S ~/proj.vim` restores splits/buffers.
- Troubleshooting: clipboard fails → check `vim --version | grep clipboard`, install `vim-gtk3` or use `"+` via xclip; slow startup → `vim --startuptime t.log` then prune plugins.
## Documentation
- `:help motion`, `:help text-objects`, `:help registers`, `:help macro`.
- Practical Vim by Drew Neil; vimcasts.org.
- https://vimhelp.org/