From d5aacad86ed56512b4cc911410965ec77a032d9e Mon Sep 17 00:00:00 2001 From: alexion Date: Sat, 4 Jul 2026 10:54:45 -0400 Subject: [PATCH] docs: refactor dotfiles skill into CLAUDE.md The skill wasn't firing reliably, so instead of polluting the global config with a skill that only helped *sometimes*, convert it into project-specific instructions in .config/dot Future work on this project (dotfiles) should always start from this directory, even if changes are made outside. This helps Claude keep the scope narrow. --- .claude/skills/dotfiles/SKILL.md | 26 -------------- .../DOT-CLI.md => .config/dot/CLAUDE.md | 34 ++++++++++++++++--- .gitea/README.md | 15 ++++---- 3 files changed, 38 insertions(+), 37 deletions(-) delete mode 100644 .claude/skills/dotfiles/SKILL.md rename .claude/skills/dotfiles/DOT-CLI.md => .config/dot/CLAUDE.md (74%) diff --git a/.claude/skills/dotfiles/SKILL.md b/.claude/skills/dotfiles/SKILL.md deleted file mode 100644 index f226ca0..0000000 --- a/.claude/skills/dotfiles/SKILL.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -name: dotfiles -description: Conventions for this machine's dotfiles bare-repo setup. Use when editing any file under $HOME managed by this repo, or when extending the dot CLI (subcommands, completions, bootstrap, tests). ---- - -# Dotfiles - -This machine's dotfiles are a bare git repo at `~/.dotfiles`, checked out with -`$HOME` as its work-tree. The `dot` fish function wraps that invocation -(`git --git-dir=~/.dotfiles --work-tree=$HOME $argv`, declared with -`--wraps=git`), so every git subcommand works through it: `dot status`, -`dot add`, `dot commit`, `dot push`, etc. - -## Always add by explicit path - -`status.showUntrackedFiles=no` is set locally, and `.gitignore` only excludes -`.dotfiles` itself plus OS/editor cruft — it is **not** a whitelist. That -means virtually everything under `$HOME` reads as untracked, and `git status` -deliberately hides all of it. - -**Always run `dot add `.** Never `dot add -A`, `dot add .`, or -any wildcard add — that would try to stage the entire home directory (caches, -secrets, everything). - -See [DOT-CLI.md](DOT-CLI.md) for the `dot` command's own architecture, -bootstrap logic, subcommand dispatch, and test suite. diff --git a/.claude/skills/dotfiles/DOT-CLI.md b/.config/dot/CLAUDE.md similarity index 74% rename from .claude/skills/dotfiles/DOT-CLI.md rename to .config/dot/CLAUDE.md index 85ba597..d5a49ba 100644 --- a/.claude/skills/dotfiles/DOT-CLI.md +++ b/.config/dot/CLAUDE.md @@ -1,6 +1,32 @@ -# The dot CLI +# Dotfiles -## Architecture +This machine's dotfiles are a bare git repo at `~/.dotfiles`, checked out with +`$HOME` as its work-tree. The `dot` fish function wraps that invocation +(`git --git-dir=~/.dotfiles --work-tree=$HOME $argv`, declared with +`--wraps=git`), so every git subcommand works through it: `dot status`, +`dot add`, `dot commit`, `dot push`, etc. + +This directory (`~/.config/dot`) holds the `dot` CLI's custom subcommands, +tests, and package lists, but the repo tracks files across `$HOME` — fish +config, git identity, the `dot` function itself, and more. To see everything +tracked, run `dot ls-tree -r --name-only HEAD` from `$HOME` (paths are shown +relative to cwd, so running it from elsewhere silently truncates the list). + +## Always add by explicit path + +`status.showUntrackedFiles=no` is set locally (see `dot init` below), and +`.gitignore` only excludes `.dotfiles` itself plus OS/editor cruft — it is +**not** a whitelist. That +means virtually everything under `$HOME` reads as untracked, and `git status` +deliberately hides all of it. + +**Always run `dot add `.** Never `dot add -A`, `dot add .`, or +any wildcard add — that would try to stage the entire home directory (caches, +secrets, everything). + +## The dot CLI + +### Architecture `dot` is defined in one file: `~/.config/fish/functions/dot.fish`. It holds three functions: @@ -32,7 +58,7 @@ sync when the listing logic changes. - explicitly sets `status.showUntrackedFiles=no` after cloning — this is a local-only git setting, so a fresh `git clone` never carries it over -## Adding a subcommand +### Adding a subcommand Beyond `init`, `dot` looks for `~/.config/dot/commands/.fish`, sources it, and calls `_dot_`. These files are deliberately kept out of @@ -49,7 +75,7 @@ of `dot` itself. 3. Add a case to `~/.config/dot/tests/dot.fish` covering it and run `fishtape ~/.config/dot/tests/dot.fish` until it passes. -## Testing +### Testing Tests live at `~/.config/dot/tests/dot.fish`, run with `fishtape ~/.config/dot/tests/dot.fish`. Fishtape is installed via Fisher diff --git a/.gitea/README.md b/.gitea/README.md index 61dca39..e8de735 100644 --- a/.gitea/README.md +++ b/.gitea/README.md @@ -14,11 +14,12 @@ fish -c 'dot init' ## Commands -| Command | Description | -| ----------- | ----------------------------------------------- | -| `dot help` | Lists available commands. | -| `dot init` | Bootstraps the dotfiles repo on a new machine. | -| `dot ` | Everything else is passed to `git`. | +| Command | Description | +| -------------- | ----------------------------------------------------------------------------------------- | +| `dot help` | Lists available commands. | +| `dot init` | Bootstraps the dotfiles repo on a new machine. | +| `dot ` | Any file under `~/.config/dot/commands/` (currently `install`); run `dot help` for the live list. | +| `dot ` | Everything else is passed to `git`. | -See [DOT-CLI.md](../.claude/skills/dotfiles/DOT-CLI.md) for the `dot` tool's -internal architecture, bootstrap logic, subcommand dispatch, and test suite. +See [CLAUDE.md](../.config/dot/CLAUDE.md) for the `dot` tool's internal +architecture, bootstrap logic, subcommand dispatch, and test suite.