skills: install only prdlk/skills, prune other sources; prompt to replace non-checkout external targets

.chezmoidata/skills.yaml

@@ -1,121 +1,18 @@
-# Agent skills, installed by the Skills CLI instead of being vendored in this
-# repo. .chezmoiscripts/run_onchange_after_25-skills.sh.tmpl re-runs whenever
-# this file changes: it installs every skill below (`skills add <source> -g -y
-# -a <agents> --skill <name>…`, one call per source) and removes CLI-installed
-# skills that are no longer listed.
+# Agent skills come from one place: github.com/prdlk/skills, installed whole by
+# the Skills CLI. .chezmoiscripts/run_onchange_after_25-skills.sh.tmpl re-runs
+# whenever this file changes: it installs every skill in the source
+# (`skills add <source> -g -y -a <agents> --skill '*'`), then removes any
+# CLI-installed skill whose recorded source is something else.
 #
-# source: anything `skills add` accepts — owner/repo (default branch), a
-#   GitHub tree URL (pins a ref or subdirectory), or a well-known endpoint URL.
-#   Skills that upstream deleted are pinned to the last ref that has them.
-# agents: optional; defaults to `agents` below. `universal` is the shared
-#   ~/.agents/skills library (Codex, Gemini CLI, OpenCode, Zed, …);
-#   `claude-code` links ~/.claude/skills/<name>.
+# source: anything `skills add` accepts. Pin a ref with a tree URL
+#   (https://github.com/prdlk/skills/tree/<ref>).
+# agents: `universal` is the shared ~/.agents/skills library (Codex, Gemini
+#   CLI, OpenCode, Zed, …); `claude-code` links ~/.claude/skills/<name>.
 #
-# Not listed (installed by other packages, never touched by the sync):
-# omarchy and diagnose-crash (/usr/share/omarchy), terminal-browser.
+# Skills that other packages install (omarchy and diagnose-crash from
+# /usr/share/omarchy, terminal-browser) are not in the CLI's lock file and are
+# never touched.
 skills:
   cli: skills@1.7.0
   agents: [universal, claude-code]
-  sources:
-    - source: affaan-m/everything-claude-code
-      skills: [rust-testing]
-    - source: apollographql/skills
-      skills: [rust-best-practices]
-    - source: charlietlamb/openlogs
-      skills: [openlogs-server-logs]
-    - source: cloudflare/skills
-      skills: [cloudflare, workers-best-practices, wrangler]
-    - source: coldteadotai/pr-lens
-      skills: [eli5, pr-lens]
-    - source: Dammyjay93/interface-design
-      skills: [interface-design]
-    - source: deckardger/tanstack-agent-skills
-      skills:
-        - tanstack-integration-best-practices
-        - tanstack-query-best-practices
-        - tanstack-router-best-practices
-        - tanstack-start-best-practices
-    - source: Doist/todoist-cli
-      skills: [todoist-cli]
-    - source: finesssee/linear-cli
-      skills: [linear-documents]
-    - source: Forward-Future/loop-library
-      skills: [loopy]
-    - source: h4ckf0r0day/obscura
-      skills: [obscura]
-    - source: hardikpandya/stop-slop
-      skills: [stop-slop]
-    - source: jeffallan/claude-skills
-      skills: [golang-pro]
-    - source: leonardomso/rust-skills
-      skills: [rust-skills]
-    - source: Leonxlnx/taste-skill
-      skills:
-        - brandkit
-        - design-taste-frontend
-        - gpt-taste
-        - high-end-visual-design
-        - imagegen-frontend-web
-        - minimalist-ui
-        - redesign-existing-projects
-    - source: mattpocock/skills
-      skills:
-        - codebase-design
-        - diagnosing-bugs
-        - domain-modeling
-        - git-guardrails-claude-code
-        - grill-me
-        - grill-with-docs
-        - grilling
-        - handoff
-        - implement
-        - improve-codebase-architecture
-        - loop-me
-        - migrate-to-shoehorn
-        - prototype
-        - scaffold-exercises
-        - setup-matt-pocock-skills
-        - setup-pre-commit
-        - tdd
-        - teach
-        - triage
-        - writing-beats
-        - writing-fragments
-        - writing-shape
-    # Removed upstream after v1.1.0 (c66bdee; writing-great-skills became
-    # writing-for-agents).
-    - source: https://github.com/mattpocock/skills/tree/v1.1.0
-      skills:
-        - design-an-interface
-        - obsidian-vault
-        - qa
-        - request-refactor-plan
-        - ubiquitous-language
-        - writing-great-skills
-    # Removed upstream in daa01d8; pinned to its parent.
-    - source: https://github.com/mattpocock/skills/tree/153fc1b93de6584562765cdce299324e1ff9e661
-      skills: [resolving-merge-conflicts]
-    - source: https://mintlify.com/docs
-      skills: [mintlify, mintlify-api, mintlify-docs]
-    - source: nextlevelbuilder/ui-ux-pro-max-skill
-      skills: [ui-ux-pro-max]
-    - source: openai/skills
-      skills: [linear]
-    - source: petergyang/no-ai-slop
-      skills: [no-ai-slop]
-    - source: remix-run/remix
-      skills: [remix, typescript-expert, write-tests]
-    - source: remotion-dev/skills
-      skills:
-        - remotion-best-practices
-        - remotion-captions
-        - remotion-create
-        - remotion-docs
-        - remotion-interactivity
-        - remotion-maps
-        - remotion-markup
-        - remotion-multimedia
-        - remotion-render
-        - remotion-saas
-        - remotion-studio
-        - remotion-upgrade
+  source: prdlk/skills

.chezmoiscripts/run_before_05-externals.sh.tmpl

@@ -0,0 +1,64 @@
+#!/bin/sh
+# Make way for git-repo externals. chezmoi can only clone into a missing or
+# empty target, and only pull in a target that is already a checkout; a
+# directory with other content stops the apply (a fresh Omarchy install ships
+# its own ~/.config/kitty, ghostty, omarchy, …). For each such target, ask
+# whether to replace it: yes moves it aside to <target>.bak-<time> and clones
+# the repo there, so chezmoi finds a checkout; no aborts the apply. Runs
+# before every apply; it only stats directories unless one is in the way.
+set -eu
+
+conflicts=$(mktemp)
+trap 'rm -f "$conflicts"' EXIT
+check() {
+    target=$1 url=$2
+    [ -e "$target" ] || [ -L "$target" ] || return 0
+    if [ -d "$target" ] && [ ! -L "$target" ]; then
+        [ -e "$target/.git" ] && return 0
+        [ -z "$(ls -A "$target")" ] && return 0
+    fi
+    printf '%s\t%s\n' "$target" "$url" >>"$conflicts"
+}
+{{- $files := glob (joinPath .chezmoi.sourceDir ".chezmoiexternals" "*.toml") }}
+{{- if stat (joinPath .chezmoi.sourceDir ".chezmoiexternal.toml") }}
+{{-   $files = append $files (joinPath .chezmoi.sourceDir ".chezmoiexternal.toml") }}
+{{- end }}
+{{- range $files }}
+{{-   range $path, $ext := include . | fromToml }}
+{{-     if eq (get $ext "type") "git-repo" }}
+check {{ joinPath $.chezmoi.destDir $path | quote }} {{ $ext.url | quote }}
+{{-     end }}
+{{-   end }}
+{{- end }}
+
+[ -s "$conflicts" ] || exit 0
+
+# A subshell: a failed redirect on the special builtin `:` would end this shell.
+if ! ( : </dev/tty ) 2>/dev/null; then
+    echo "error: these git-repo external targets exist and are not checkouts:" >&2
+    cut -f1 "$conflicts" | sed 's/^/  /' >&2
+    echo "Run chezmoi apply in a terminal to be asked about each, or move them aside." >&2
+    exit 1
+fi
+
+stamp=$(date +%Y%m%d-%H%M%S)
+while IFS="$(printf '\t')" read -r target url; do
+    printf '%s exists and is not a git checkout. Replace it with %s (old copy kept as %s.bak-%s)? [y/N] ' \
+        "$target" "$url" "$target" "$stamp" >/dev/tty
+    read -r answer </dev/tty || answer=''
+    case $answer in
+    [yY]*) ;;
+    *)
+        echo "error: kept $target; chezmoi cannot apply its external. Move it aside or answer y, then apply again." >&2
+        exit 1
+        ;;
+    esac
+    mv "$target" "$target.bak-$stamp"
+    if ! git clone --quiet "$url" "$target"; then
+        rm -rf "$target"
+        mv "$target.bak-$stamp" "$target"
+        echo "error: cloning $url failed; $target restored." >&2
+        exit 1
+    fi
+    echo "$target: cloned $url (old copy in $target.bak-$stamp)"
+done <"$conflicts"

.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl

@@ -1,15 +1,17 @@
 #!/bin/sh
 # Sync agent skills with .chezmoidata/skills.yaml through the Skills CLI:
-# install every declared skill (one `skills add` per source), then remove
-# skills a previous run installed that are no longer declared.
+# install every skill in the one declared source, then remove every
+# CLI-installed skill that came from anywhere else.
 # skills hash: {{ .skills | toJson | sha256sum }}
 set -u
 
 command -v npx >/dev/null 2>&1 || { echo "warning: npx not found — skipping skills sync" >&2; exit 0; }
+command -v jq >/dev/null 2>&1 || { echo "warning: jq not found — skipping skills sync" >&2; exit 0; }
 
 src={{ .chezmoi.sourceDir | quote }}
-state=${XDG_STATE_HOME:-$HOME/.local/state}/chezmoi/skills.txt
-declared='{{ range .skills.sources }}{{ range .skills }} {{ . }}{{ end }}{{ end }} '
+source={{ .skills.source | quote }}
+agents={{ .skills.agents | join " " | quote }}
+lock=${XDG_STATE_HOME:-$HOME/.local/state}/skills/.skill-lock.json
 
 skills() { npx -y {{ .skills.cli | quote }} "$@" </dev/null; }
 
@@ -23,48 +25,28 @@ for dir in "$HOME/.agents/skills"/* "$HOME/.claude/skills"/*; do
         rm -rf "$dir"
     fi
 done
-lock=$HOME/.agents/.skill-lock.json
-if [ -L "$lock" ]; then
-    case $(readlink "$lock") in "$src"/*) rm -f "$lock" ;; esac
+old_lock=$HOME/.agents/.skill-lock.json
+if [ -L "$old_lock" ]; then
+    case $(readlink "$old_lock") in "$src"/*) rm -f "$old_lock" ;; esac
 fi
+# State file of the old per-skill sync; the CLI's lock file replaces it.
+rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/chezmoi/skills.txt"
 
-# Remove what the last sync installed but skills.yaml no longer lists.
-stale=''
-if [ -f "$state" ]; then
-    while IFS= read -r name; do
-        case $declared in *" $name "*) ;; *) stale="$stale $name" ;; esac
-    done <"$state"
-fi
-if [ -n "$stale" ]; then
-    echo "skills: removing$stale"
-    # shellcheck disable=SC2086 # one word per skill name
-    skills remove -g -y $stale || echo "warning: skills remove failed:$stale" >&2
-fi
-
-failed=''
-log=$(mktemp)
-trap 'rm -f "$log"' EXIT
-add() {
-    source=$1 agents=$2
-    shift 2
-    echo "skills: $source → $*"
-    # shellcheck disable=SC2086 # agents is a space-separated list
-    if ! skills add "$source" -g -y -a $agents --skill "$@" >"$log" 2>&1; then
-        failed="$failed $source"
-        tail -n 8 "$log" >&2
-    fi
-}
-{{ range .skills.sources -}}
-{{ $agents := $.skills.agents -}}
-{{ if hasKey . "agents" }}{{ $agents = .agents }}{{ end -}}
-add {{ .source | quote }} {{ $agents | join " " | quote }}{{ range .skills }} {{ . | quote }}{{ end }}
-{{ end -}}
-
-mkdir -p "$(dirname "$state")"
-printf '%s\n' $declared >"$state"
-
-if [ -n "$failed" ]; then
-    # Non-zero keeps the old hash, so the next `chezmoi apply` retries.
-    echo "error: skills add failed for:$failed" >&2
+echo "skills: $source → all skills"
+# shellcheck disable=SC2086 # agents is a space-separated list
+if ! skills add "$source" -g -y -a $agents --skill '*'; then
+    # Non-zero keeps the old hash, so the next `chezmoi apply` retries. Nothing
+    # is removed while the install is broken.
+    echo "error: skills add failed for $source" >&2
     exit 1
 fi
+
+# The lock records each skill's source as owner/repo, also for tree URLs.
+repo=$(printf '%s\n' "$source" | sed -E 's#^https://github\.com/##; s#(\.git)?(/tree/.*)?/?$##')
+stale=$(jq -r --arg repo "$repo" \
+    '.skills // {} | to_entries[] | select(.value.source != $repo) | .key' "$lock" 2>/dev/null)
+if [ -n "$stale" ]; then
+    echo "skills: removing" $stale
+    # shellcheck disable=SC2086 # one word per skill name
+    skills remove -g -y $stale || { echo "error: skills remove failed" >&2; exit 1; }
+fi

README.md

@@ -48,10 +48,11 @@ so all shells share one implementation; helpers that must mutate shell state
 (`cd`-style) are per-shell functions in `fish/functions/`, `bash/functions/`,
 and `zsh/functions/`.
 
-Agent skills are not vendored: `.chezmoidata/skills.yaml` lists every
-skill and its upstream source, and
-`.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` installs them with the
-Skills CLI whenever that file changes.
+Agent skills are not vendored: they all come from
+[prdlk/skills](https://github.com/prdlk/skills), and
+`.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` installs every skill in
+it with the Skills CLI (removing skills from any other source) whenever
+`.chezmoidata/skills.yaml` changes.
 
 Omarchy layer (roles `desktop`/`laptop`): `dot_config/hypr` (submodule),
 `dot_config/waybar`, `dot_config/uwsm`, fontconfig, mimeapps,

docs/ai/README.md

@@ -4,13 +4,13 @@ The shared agent skill library and the shell entry points for coding agents.
 
 The repo manages the agent skill library only. Claude Code (`~/.claude`) and omp (`~/.omp`) configs are not in this repo. omp, opencode, and crush are global mise tools (`packages.shared.mise`, installed by [15-tools](../chezmoi/scripts.md#15-tools)) and are updated by topgrade's `mise upgrade`; no other agent CLI is installed by chezmoi.
 
-- [Skills](skills.md): Agent skills declared in `.chezmoidata/skills.yaml` and installed into `~/.agents/skills` and `~/.claude/skills` by an apply script.
+- [Skills](skills.md): Every agent skill in [prdlk/skills](https://github.com/prdlk/skills), installed into `~/.agents/skills` and `~/.claude/skills` by an apply script.
 
 ## Pages
 
 | Page | Source in repo | Target in `$HOME` | Covers |
 | --- | --- | --- | --- |
-| [Skills](skills.md) | `.chezmoidata/skills.yaml`, `.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` | `~/.agents/skills/`, `~/.claude/skills/` | Skill list and sources; installed by the Skills CLI, not vendored |
+| [Skills](skills.md) | `.chezmoidata/skills.yaml`, `.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` | `~/.agents/skills/`, `~/.claude/skills/` | The prdlk/skills source and skill list; installed by the Skills CLI, not vendored |
 
 ## Shell entry points
 

docs/ai/skills.md

@@ -1,14 +1,14 @@
 # Skills
 
-Agent skills declared in .chezmoidata/skills.yaml and installed into ~/.agents/skills and ~/.claude/skills by a chezmoi script.
+Agent skills from [prdlk/skills](https://github.com/prdlk/skills), installed into ~/.agents/skills and ~/.claude/skills by a chezmoi script.
 
-Agent skills are folders with a `SKILL.md` file (frontmatter `name` and `description`, then instructions) that agents load on demand. The repo does not vendor them. It declares each skill and its source in `.chezmoidata/skills.yaml`, and the `run_onchange_after_25-skills.sh.tmpl` script installs them with the Skills CLI (`npx skills`) on `chezmoi apply`.
+Agent skills are folders with a `SKILL.md` file (frontmatter `name` and `description`, then instructions) that agents load on demand. The repo does not vendor or list them: [prdlk/skills](https://github.com/prdlk/skills) is the single source, and `run_onchange_after_25-skills.sh.tmpl` installs every skill in it with the Skills CLI (`npx skills`) on `chezmoi apply`. Any skill the CLI installed from another source is removed.
 
 ## Files
 
 | Source in repo | Target | Notes |
 | --- | --- | --- |
-| `.chezmoidata/skills.yaml` | chezmoi data `.skills` | CLI version, default agents, and one entry per source |
+| `.chezmoidata/skills.yaml` | chezmoi data `.skills` | CLI version, agents, and the one source |
 | `.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` | runs `skills add` / `skills remove` | Re-runs when `.skills` changes; see [Scripts](../chezmoi/scripts.md#25-skills) |
 
 Not role-gated; the sync runs on every machine. Installed skill files are machine state, not repo files:
@@ -16,203 +16,129 @@ Not role-gated; the sync runs on every machine. Installed skill files are machin
 | Path | Written by | Contents |
 | --- | --- | --- |
 | `~/.agents/skills/<name>/` | Skills CLI | Shared library for `universal` installs, read by Codex, Gemini CLI, OpenCode, Zed, … |
-| `~/.claude/skills/<name>` | Skills CLI | Relative symlink `../../.agents/skills/<name>` for universal installs; a real copied directory for Claude-only installs |
-| `$XDG_STATE_HOME/skills/.skill-lock.json` | Skills CLI | The CLI's own install record (`~/.agents/.skill-lock.json` when `XDG_STATE_HOME` is unset) |
-| `${XDG_STATE_HOME:-~/.local/state}/chezmoi/skills.txt` | sync script | Skill names installed by the previous sync, used to remove undeclared ones |
+| `~/.claude/skills/<name>` | Skills CLI | Relative symlink `../../.agents/skills/<name>` |
+| `${XDG_STATE_HOME:-~/.local/state}/skills/.skill-lock.json` | Skills CLI | The CLI's install record: each skill's `source` (`owner/repo`), path, and hash. The sync reads it to find skills from other sources |
 
 ## skills.yaml
 
 ```yaml
 skills:
   cli: skills@1.7.0                 # pinned CLI, run via npx -y
-  agents: [universal, claude-code]  # default install targets
-  sources:
-    - source: cloudflare/skills
-      agents: [claude-code]         # Claude Code only
-      skills: [agents-sdk, durable-objects]
+  agents: [universal, claude-code]  # install targets
+  source: prdlk/skills              # every skill in this repo is installed
 ```
 
 | Key | Meaning |
 | --- | --- |
 | `cli` | npm spec of the Skills CLI, run as `npx -y <cli>` |
-| `agents` | Default `-a` targets. `universal` is `~/.agents/skills`; `claude-code` is `~/.claude/skills` |
-| `sources[].source` | Anything `skills add` accepts: `owner/repo` (default branch), a GitHub tree URL (pins a ref or subdirectory), or a well-known endpoint URL |
-| `sources[].skills` | Skill names to install from that source (`--skill`) |
-| `sources[].agents` | Optional override of the default `agents` |
-
-108 skills across 42 source entries. `cloudflare/skills` appears twice: once with the defaults, once with `agents: [claude-code]`.
-
-### Pinned sources
-
-Unpinned sources track the upstream default branch, so skill content updates whenever the sync runs. Skills that upstream deleted or renamed are pinned to the last ref that still has them:
-
-| Source | Skills | Reason |
-| --- | --- | --- |
-| `https://github.com/mattpocock/skills/tree/v1.1.0` | `design-an-interface`, `obsidian-vault`, `qa`, `request-refactor-plan`, `ubiquitous-language`, `writing-great-skills` | Removed upstream in c66bdee (`writing-great-skills` became `writing-for-agents`) |
-| `https://github.com/mattpocock/skills/tree/153fc1b…` | `resolving-merge-conflicts` | Removed upstream in daa01d8 |
-| `https://github.com/terrylica/cc-skills/tree/6d35f84…` | `mise-tasks` | Retired upstream in dd0d3f2f |
-| `https://github.com/cloudflare/skills/tree/30553f8…` | `sandbox-sdk` | Replaced upstream by `sandbox-stable` / `sandbox-next` in f96bff7 |
-
-`create-beads-orchestration` uses the subdirectory URL `https://github.com/AvivK5498/Claude-Code-Beads-Orchestration/tree/main/skills/create-beads-orchestration`, because the bare repo's root `SKILL.md` would install the whole repository as the skill. The Mintlify skills come from the well-known endpoint `https://mintlify.com/docs`.
+| `agents` | `-a` targets. `universal` is `~/.agents/skills`; `claude-code` is `~/.claude/skills` |
+| `source` | Anything `skills add` accepts. `prdlk/skills` tracks its default branch; `https://github.com/prdlk/skills/tree/<ref>` pins a ref |
 
 ### Not managed
 
-`omarchy` and `diagnose-crash` (symlinks into `/usr/share/omarchy`) and `terminal-browser` are installed by other packages. They are not in `skills.yaml`, and the sync never touches them.
+`omarchy`, `omarchy-app` and `diagnose-crash` (symlinks into `/usr/share/omarchy`) and `terminal-browser` are installed by other packages. They are not in the CLI's lock file, so the sync never touches them.
 
 ## Managing skills
 
-Find a skill's source and name with the CLI, then declare it:
-
-```sh
-npx skills find <query>              # search the registry
-npx skills add <source> --list       # list the skills a source provides
-```
-
-- **Add**: add the name under its source in `.chezmoidata/skills.yaml` (or a new `source` entry) and run `chezmoi apply`.
-- **Remove**: delete the name and run `chezmoi apply`; the sync runs `skills remove` for it.
-- **Claude Code only**: put it in an entry with `agents: [claude-code]`.
-
-Do not `npx skills add` by hand and expect chezmoi to track it; only `skills.yaml` is the record. The script only re-runs when `.skills` changes, so unpinned sources pick up upstream updates on the next sync after an edit to `skills.yaml`.
+- **Add or remove a skill**: change it in [prdlk/skills](https://github.com/prdlk/skills) and push. The script only re-runs when `.skills` changes, so pull the change in with `npx -y skills@1.7.0 update -g`, or re-run the sync by editing `skills.yaml` (for example pinning a new ref).
+- **Skills from other sources**: not supported. A skill added with `npx skills add <other>` is removed by the next sync; add it to prdlk/skills instead.
 
 ## How the sync works
 
 1. **Trigger**
 
-   The script is `run_onchange_after_`: chezmoi re-runs it after applying files whenever the sha256 of `.skills` (as JSON) changes. If `npx` is missing it warns and skips.
+   The script is `run_onchange_after_`: chezmoi re-runs it after applying files whenever the sha256 of `.skills` (as JSON) changes. If `npx` or `jq` is missing it warns and skips.
 
 2. **Migrate**
 
-   One-time cleanup of the old vendored layout: deletes any directory in `~/.agents/skills` or `~/.claude/skills` that contains symlinks into the chezmoi source directory, and removes `~/.agents/.skill-lock.json` if it is a symlink into the source directory.
+   One-time cleanup: deletes any directory in `~/.agents/skills` or `~/.claude/skills` that contains symlinks into the chezmoi source directory (the old vendored layout), removes `~/.agents/.skill-lock.json` if it is a symlink into the source directory, and deletes the old per-skill state file `~/.local/state/chezmoi/skills.txt`.
 
-3. **Remove**
+3. **Install**
 
-   Skills listed in `skills.txt` (the previous sync) but no longer declared are removed with `skills remove -g -y`.
+   `skills add <source> -g -y -a <agents> --skill '*'` installs every skill in the source. A skill already installed from another source under the same name is reinstalled from prdlk/skills, and the lock records the new source.
 
-4. **Install**
+4. **Prune**
 
-   One `skills add <source> -g -y -a <agents> --skill <names…>` per source entry. Output is captured; on failure the last 8 lines are printed.
+   Every lock entry whose `source` is not the configured repo (tree URLs reduced to `owner/repo`) is removed with `skills remove -g -y`.
 
-5. **Record**
+5. **Retry**
 
-   The declared names are written to `skills.txt`. Claude-only (`-a claude-code`) installs are not recorded in the CLI lock, which is why the script keeps its own state file.
+   If the install or the removal fails the script exits 1, so chezmoi keeps the old hash and runs it again on the next apply. A failed install removes nothing.
 
-6. **Retry**
-
-   If any source failed the script exits 1, so chezmoi keeps the old hash and runs it again on the next apply.
-
-Every universal skill gets both a `~/.agents/skills` directory and a `~/.claude/skills` link. Claude Code resolves `~/.claude/skills/<name>` → `../../.agents/skills/<name>`, so both read the same files.
+Every skill gets both a `~/.agents/skills` directory and a `~/.claude/skills` link. Claude Code resolves `~/.claude/skills/<name>` → `../../.agents/skills/<name>`, so both read the same files.
 
 ## Library
 
-The Description column is the first sentence of each installed skill's `SKILL.md` frontmatter `description`. Source is the `source` from `skills.yaml` (GitHub URLs shortened to `owner/repo/tree/<ref>`). Agents `claude-code` means the skill is installed as a real directory in `~/.claude/skills` only.
+The 69 skills in prdlk/skills when this page was written. The Description column is the first sentence of each skill's `SKILL.md` frontmatter `description`.
 
-| Skill | Source | Agents | Description |
-| --- | --- | --- | --- |
-| `absurd` | `earendil-works/absurd` | claude-code | Debug and operate Absurd durable workflows with absurdctl. |
-| `agents-sdk` | `cloudflare/skills` | claude-code | Build, debug, or review Cloudflare Agents SDK applications using the agents package. |
-| `brandkit` | `Leonxlnx/taste-skill` | universal + claude-code | Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. |
-| `bun-development` | `sickn33/antigravity-awesome-skills` | universal + claude-code | Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun). |
-| `cloudflare` | `cloudflare/skills` | universal + claude-code | Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. |
-| `cloudflare-email-service` | `cloudflare/skills` | claude-code | Implement or troubleshoot Cloudflare Email Sending and Email Routing integrations and their delivery configuration. |
-| `cloudflare-one` | `cloudflare/skills` | claude-code | Design, configure, troubleshoot, or review Cloudflare One Zero Trust and SASE deployments. |
-| `cloudflare-one-migrations` | `cloudflare/skills` | claude-code | Assess and plan migrations from existing VPN, SWG, or SASE platforms to Cloudflare One, including policy mapping, parity gaps, and rollout. |
-| `codebase-design` | `mattpocock/skills` | universal + claude-code | Shared vocabulary for designing deep modules. |
-| `core` | `vercel-labs/json-render` | universal + claude-code | Core package for defining schemas, catalogs, and AI prompt generation for json-render. |
-| `create-beads-orchestration` | `AvivK5498/Claude-Code-Beads-Orchestration/tree/main/skills/create-beads-orchestration` | claude-code | Bootstrap lean multi-agent orchestration with beads task tracking. |
-| `deepinit` | `yeachan-heo/oh-my-claudecode` | universal + claude-code | Deep codebase initialization with hierarchical AGENTS.md documentation |
-| `design-an-interface` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Generate multiple radically different interface designs for a module using parallel sub-agents. |
-| `design-taste-frontend` | `Leonxlnx/taste-skill` | universal + claude-code | Anti-slop frontend skill for landing pages, portfolios, and redesigns. |
-| `diagnosing-bugs` | `mattpocock/skills` | universal + claude-code | Diagnosis loop for hard bugs and performance regressions. |
-| `domain-modeling` | `mattpocock/skills` | universal + claude-code | Build and sharpen a project's domain model. |
-| `durable-objects` | `cloudflare/skills` | claude-code | Build, debug, or review Cloudflare Durable Objects code for persistent state and coordination. |
-| `eli5` | `coldteadotai/pr-lens` | universal + claude-code | Explains a codebase, a folder, a feature, a command or a pull request to someone who knows nothing about it, as a PR Lens canvas whose walkthrough builds the picture one part at a time. |
-| `find-skills` | `vercel-labs/skills` | universal + claude-code | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. |
-| `fumadocs-component-docs` | `TheOrcDev/8bitcn-ui` | universal + claude-code | Create component documentation with installation, usage examples, and preview sections. |
-| `fumadocs-mdx-structure` | `TheOrcDev/8bitcn-ui` | universal + claude-code | Create MDX documentation files with proper frontmatter, imports, and component integration. |
-| `fumadocs-registry-integration` | `TheOrcDev/8bitcn-ui` | universal + claude-code | Register 8-bit components in registry.json for shadcn/ui add command. |
-| `git-guardrails-claude-code` | `mattpocock/skills` | universal + claude-code | Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. |
-| `golang-pro` | `jeffallan/claude-skills` | universal + claude-code | Implements concurrent Go patterns using goroutines and channels, designs and builds microservices with gRPC or REST, optimizes Go application performance with pprof, and enforces idiomatic Go with generics, interfaces, and robust error handling. |
-| `gpt-taste` | `Leonxlnx/taste-skill` | universal + claude-code | Elite UX/UI & Advanced GSAP Motion Engineer. |
-| `grill-me` | `mattpocock/skills` | universal + claude-code | A relentless interview to sharpen a plan or design. |
-| `grill-with-docs` | `mattpocock/skills` | universal + claude-code | A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. |
-| `grilling` | `mattpocock/skills` | universal + claude-code | Grill the user relentlessly about a plan, decision, or idea. |
-| `handoff` | `mattpocock/skills` | universal + claude-code | Compact the current conversation into a handoff document for another agent to pick up. |
-| `high-end-visual-design` | `Leonxlnx/taste-skill` | universal + claude-code | Teaches the AI to design like a high-end agency. |
-| `imagegen-frontend-web` | `Leonxlnx/taste-skill` | universal + claude-code | Elite frontend image-direction skill for generating premium, conversion-aware website design references. |
-| `implement` | `mattpocock/skills` | universal + claude-code | Implement a piece of work based on a spec or set of tickets. |
-| `improve-codebase-architecture` | `mattpocock/skills` | universal + claude-code | Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. |
-| `interface-design` | `Dammyjay93/interface-design` | universal + claude-code | Craft-first interface design for dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces, and interactive products. |
-| `laws-of-ux` | `RoleModel/rolemodel-skills` | universal + claude-code | Review and guide UI implementations using the 21 Laws of UX. |
-| `linear` | `openai/skills` | universal + claude-code | Manage issues, projects & team workflows in Linear. |
-| `linear-cli` | `schpet/linear-cli` | universal + claude-code | Manage Linear issues from the command line using the linear cli. |
-| `linear-documents` | `finesssee/linear-cli` | universal + claude-code | Manage Linear documents. |
-| `loop-me` | `mattpocock/skills` | universal + claude-code | Grill me about specs for the workflows I want to build, within this workspace. |
-| `loopy` | `Forward-Future/loop-library` | universal + claude-code | Discover, find, compare, audit, repair, adapt, craft, run, debrief, save, and prepare repeatable AI-agent loops for publication. |
-| `migrate-to-shoehorn` | `mattpocock/skills` | universal + claude-code | Migrate test files from `as` type assertions to @total-typescript/shoehorn. |
-| `minimalist-ui` | `Leonxlnx/taste-skill` | universal + claude-code | Clean editorial-style interfaces. |
-| `mintlify` | `https://mintlify.com/docs` | universal + claude-code | Build and maintain documentation sites with Mintlify. |
-| `mintlify-api` | `https://mintlify.com/docs` | universal + claude-code | Interact with the Mintlify REST API to manage deployments, trigger builds, and query documentation site metadata programmatically. |
-| `mintlify-docs` | `https://mintlify.com/docs` | universal + claude-code | Build and maintain documentation sites with Mintlify. |
-| `mise-tasks` | `terrylica/cc-skills/tree/6d35f84` | universal + claude-code | Orchestrate multi-step project workflows using mise task definitions with dependency management and argument handling. |
-| `native-sdk` | `vercel-labs/native` | universal + claude-code | Discovery skill for the Native SDK, the complete toolkit for building native desktop applications. |
-| `no-ai-slop` | `petergyang/no-ai-slop` | universal + claude-code | Edit drafts into sharper, more human writing while preserving the writer's personal voice, or detect AI-slop patterns without rewriting. |
-| `obscura` | `h4ckf0r0day/obscura` | universal + claude-code | Operate and validate Obscura for JavaScript page loading, stealth browsing, anti-fingerprinting, and browser automation. |
-| `obsidian-vault` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. |
-| `openlogs-server-logs` | `charlietlamb/openlogs` | universal + claude-code | Fetch and inspect recent local server logs in repos that use openlogs or the `ol` CLI. |
-| `pr-lens` | `coldteadotai/pr-lens` | universal + claude-code | Draws a code change or part of a codebase as an animated architecture or data-flow diagram, on its own or in a pull request. |
-| `prototype` | `mattpocock/skills` | universal + claude-code | Build a throwaway prototype to answer a design question. |
-| `qa` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. |
-| `react` | `vercel-labs/json-render` | universal + claude-code | React renderer for json-render that turns JSON specs into React components. |
-| `react-email` | `vercel-labs/json-render` | universal + claude-code | React Email renderer for json-render that turns JSON specs into HTML or plain-text emails using @react-email/components and @react-email/render. |
-| `redesign-existing-projects` | `Leonxlnx/taste-skill` | universal + claude-code | Upgrades existing websites and apps to premium quality. |
-| `remix` | `remix-run/remix` | universal + claude-code | Builds, reviews, and refactors Remix 3 apps using the remix package and remix/* imports. |
-| `remotion-best-practices` | `remotion-dev/skills` | universal + claude-code | Router for all Remotion skills |
-| `remotion-captions` | `remotion-dev/skills` | universal + claude-code | Transcribing, displaying and animating captions |
-| `remotion-create` | `remotion-dev/skills` | universal + claude-code | Create a new Remotion video |
-| `remotion-docs` | `remotion-dev/skills` | universal + claude-code | Search Remotion documentation |
-| `remotion-interactivity` | `remotion-dev/skills` | universal + claude-code | Structure Remotion markup for interactivity |
-| `remotion-maps` | `remotion-dev/skills` | universal + claude-code | Remotion Map animation knowledge |
-| `remotion-markup` | `remotion-dev/skills` | universal + claude-code | Content, animation and effects best practices |
-| `remotion-multimedia` | `remotion-dev/skills` | universal + claude-code | Interacting with Mediabunny |
-| `remotion-render` | `remotion-dev/skills` | universal + claude-code | Export a Remotion video |
-| `remotion-saas` | `remotion-dev/skills` | universal + claude-code | Build an app with Remotion |
-| `remotion-studio` | `remotion-dev/skills` | universal + claude-code | Preview a Remotion video |
-| `remotion-upgrade` | `remotion-dev/skills` | universal + claude-code | Upgrade Remotion, and related packages |
-| `request-refactor-plan` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. |
-| `resolving-merge-conflicts` | `mattpocock/skills/tree/153fc1b` | universal + claude-code | Use when you need to resolve an in-progress git merge/rebase conflict. |
-| `rust-async-patterns` | `wshobson/agents` | universal + claude-code | Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. |
-| `rust-best-practices` | `apollographql/skills` | universal + claude-code | Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. |
-| `rust-skills` | `leonardomso/rust-skills` | universal + claude-code | Comprehensive Rust coding guidelines with 265 rules across 26 categories. |
-| `rust-testing` | `affaan-m/everything-claude-code` | universal + claude-code | Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. |
-| `sandbox-sdk` | `cloudflare/skills/tree/30553f8` | claude-code | Build sandboxed applications for secure code execution. |
-| `scaffold-exercises` | `mattpocock/skills` | universal + claude-code | Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. |
-| `setup-matt-pocock-skills` | `mattpocock/skills` | universal + claude-code | Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. |
-| `setup-pre-commit` | `mattpocock/skills` | universal + claude-code | Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. |
-| `shadcn` | `shadcn-ui/ui` | universal + claude-code | Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. |
-| `solidity-foundry-development` | `whackur/solidity-agent-toolkit` | universal + claude-code | Foundry development workflow for Solidity smart contracts. |
-| `solidity-security` | `wshobson/agents` | universal + claude-code | Master smart contract security best practices to prevent common vulnerabilities and implement secure Solidity patterns. |
-| `stop-slop` | `hardikpandya/stop-slop` | universal + claude-code | Remove AI writing patterns from prose. |
-| `tanstack-form` | `tanstack-skills/tanstack-skills` | universal + claude-code | Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, Lit, and Svelte. |
-| `tanstack-integration-best-practices` | `deckardger/tanstack-agent-skills` | universal + claude-code | Best practices for integrating TanStack Query with TanStack Router and TanStack Start. |
-| `tanstack-query-best-practices` | `deckardger/tanstack-agent-skills` | universal + claude-code | TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. |
-| `tanstack-router-best-practices` | `deckardger/tanstack-agent-skills` | universal + claude-code | TanStack Router best practices for type-safe routing, data loading, search params, and navigation. |
-| `tanstack-start-best-practices` | `deckardger/tanstack-agent-skills` | universal + claude-code | TanStack Start best practices for full-stack React applications. |
-| `tanstack-table` | `tanstack-skills/tanstack-skills` | universal + claude-code | Headless UI for building powerful tables & datagrids for TS/JS, React, Vue, Solid, Svelte, Qwik, Angular, and Lit. |
-| `tdd` | `mattpocock/skills` | universal + claude-code | Test-driven development. |
-| `teach` | `mattpocock/skills` | universal + claude-code | Teach the user a new skill or concept, within this workspace. |
-| `todoist-cli` | `Doist/todoist-cli` | universal + claude-code | Manage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. |
-| `triage` | `mattpocock/skills` | universal + claude-code | Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs. |
-| `turnstile-spin` | `cloudflare/skills` | claude-code | Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify. |
-| `typescript-expert` | `remix-run/remix` | universal + claude-code | Write, refactor, or review TypeScript code with strict, precise, maintainable types and without unnecessary `any`, type assertions, or type suppressions. |
-| `ubiquitous-language` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. |
-| `ui-ux-pro-max` | `nextlevelbuilder/ui-ux-pro-max-skill` | universal + claude-code | UI/UX design intelligence for web, mobile, and desktop. |
-| `uv-package-manager` | `wshobson/agents` | universal + claude-code | Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. |
-| `web-design-guidelines` | `vercel-labs/agent-skills` | universal + claude-code | Review UI code for Web Interface Guidelines compliance. |
-| `web-perf` | `cloudflare/skills` | claude-code | Audit, diagnose, or optimize website loading and interaction performance, Core Web Vitals, and Lighthouse performance scores. |
-| `workers-best-practices` | `cloudflare/skills` | universal + claude-code | Cloudflare Workers best practices for production applications. |
-| `wrangler` | `cloudflare/skills` | universal + claude-code | Run or troubleshoot Wrangler CLI commands and configure Worker projects for local development, Previews, deployment, and Cloudflare resource management. |
-| `write-tests` | `remix-run/remix` | universal + claude-code | Write, refactor, or review tests in the Remix repository. |
-| `writing-beats` | `mattpocock/skills` | universal + claude-code | Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it. |
-| `writing-fragments` | `mattpocock/skills` | universal + claude-code | Writing, explore: mine raw fragments, no structure yet. |
-| `writing-great-skills` | `mattpocock/skills/tree/v1.1.0` | universal + claude-code | Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. |
-| `writing-shape` | `mattpocock/skills` | universal + claude-code | Writing, exploit: shape raw material into an article, paragraph by paragraph. |
+| Skill | Description |
+| --- | --- |
+| `absurd` | Debug and operate Absurd durable workflows with absurdctl. |
+| `attach-db` | Attach a DuckDB database file for use with /duckdb-skills:query. |
+| `blume` | Build and maintain documentation sites with Blume, the markdown-first docs framework on Astro and Vite. |
+| `blume-migrate` | Migrate an existing documentation site (Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, or any docs framework) to Blume, the markdown-first docs framework on Astro. |
+| `blume-update-docs` | Keep a Blume docs site in sync with the product it documents. |
+| `cloudflare` | Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. |
+| `cloudflare-email-service` | Implement or troubleshoot Cloudflare Email Sending and Email Routing integrations and their delivery configuration. |
+| `codebase-design` | Shared vocabulary for designing deep modules. |
+| `deepinit` | Deep codebase initialization with hierarchical AGENTS.md documentation |
+| `design-taste-frontend` | Anti-slop frontend skill for landing pages, portfolios, and redesigns. |
+| `duckdb-docs` | Search DuckDB and DuckLake documentation and blog posts. |
+| `durable-objects` | Build, debug, or review Cloudflare Durable Objects code for persistent state and coordination. |
+| `find-skills` | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. |
+| `golang-pro` | Implements concurrent Go patterns using goroutines and channels, designs and builds microservices with gRPC or REST, optimizes Go application performance with pprof, and enforces idiomatic Go with generics, interfaces, and robust error handling. |
+| `grill-me` | A relentless interview to sharpen a plan or design. |
+| `grill-with-docs` | A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. |
+| `grilling` | Grill the user relentlessly about a plan, decision, or idea. |
+| `gum` | Gum 0.17.x for interactive and formatted terminal scripts: all 13 commands, GUM_* variables, the stdout/stderr and exit-code contract, theming, and shell traps. |
+| `high-end-visual-design` | Teaches the AI to design like a high-end agency. |
+| `improve-codebase-architecture` | Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. |
+| `interface-design` | Craft-first interface design for dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces, and interactive products. |
+| `laws-of-ux` | Review and guide UI implementations using the 21 Laws of UX. |
+| `minimalist-ui` | Clean editorial-style interfaces. |
+| `mise-expert` | Mise development environment manager (asdf + direnv + make replacement). |
+| `no-ai-slop` | Edit drafts into sharper, more human writing while preserving the writer's personal voice, or detect AI-slop patterns without rewriting. |
+| `obscura` | Operate and validate Obscura for JavaScript page loading, stealth browsing, anti-fingerprinting, tracker blocking, screenshots and visual comparison, CDP automation with Puppeteer or Playwright, screencasting, PDF export, MCP browser interaction, and web extraction. |
+| `obsidian-vault` | Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. |
+| `openlogs-server-logs` | Fetch and inspect recent local server logs in repos that use openlogs or the `ol` CLI. |
+| `pr-lens` | WHAT: Draws a code change or part of a codebase as an animated architecture or data-flow diagram, on its own or in a pull request. |
+| `prototype` | Build a throwaway prototype to answer a design question. |
+| `qa` | Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. |
+| `query` | Run SQL queries against the attached DuckDB database or ad-hoc against files. |
+| `react` | React renderer for json-render that turns JSON specs into React components. |
+| `react-email` | React Email renderer for json-render that turns JSON specs into HTML or plain-text emails using @react-email/components and @react-email/render. |
+| `remotion-best-practices` | Router for all Remotion skills |
+| `remotion-captions` | Transcribing, displaying and animating captions |
+| `remotion-create` | Create a new Remotion video |
+| `remotion-docs` | Search Remotion documentation |
+| `remotion-interactivity` | Structure Remotion markup for interactivity |
+| `remotion-maps` | Remotion Map animation knowledge |
+| `remotion-markup` | Content, animation and effects best practices |
+| `remotion-multimedia` | Interacting with Mediabunny |
+| `remotion-render` | Export a Remotion video |
+| `remotion-saas` | Build an app with Remotion |
+| `remotion-studio` | Preview a Remotion video |
+| `remotion-upgrade` | Upgrade Remotion, and related packages |
+| `request-refactor-plan` | Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. |
+| `resolving-merge-conflicts` | Use when you need to resolve an in-progress git merge/rebase conflict. |
+| `rust-async-patterns` | Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. |
+| `rust-best-practices` | Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. |
+| `rust-skills` | Comprehensive Rust coding guidelines with 265 rules across 26 categories. |
+| `rust-testing` | Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. |
+| `setup-matt-pocock-skills` | Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. |
+| `shadcn` | Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. |
+| `stop-slop` | Remove AI writing patterns from prose. |
+| `tanstack-form` | Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, Lit, and Svelte. |
+| `tanstack-integration-best-practices` | Best practices for integrating TanStack Query with TanStack Router and TanStack Start. |
+| `tanstack-query-best-practices` | TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. |
+| `tanstack-router-best-practices` | TanStack Router best practices for type-safe routing, data loading, search params, and navigation. |
+| `tanstack-start-best-practices` | TanStack Start best practices for full-stack React applications. |
+| `tanstack-table` | Headless UI for building powerful tables & datagrids for TS/JS, React, Vue, Solid, Svelte, Qwik, Angular, and Lit. |
+| `tdd` | Test-driven development. |
+| `typescript-expert` | Write, refactor, or review TypeScript code with strict, precise, maintainable types and without unnecessary `any`, type assertions, or type suppressions. |
+| `ui-ux-pro-max` | UI/UX design intelligence for web, mobile, and desktop. |
+| `uv-package-manager` | Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. |
+| `web-design-guidelines` | Review UI code for Web Interface Guidelines compliance. |
+| `web-perf` | Audit, diagnose, or optimize website loading and interaction performance, Core Web Vitals, and Lighthouse performance scores. |
+| `workers-best-practices` | Cloudflare Workers best practices for production applications. |
+| `wrangler` | Run or troubleshoot Wrangler CLI commands and configure Worker projects for local development, Previews, deployment, and Cloudflare resource management. |

docs/chezmoi/README.md

@@ -36,6 +36,7 @@ The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/Cod
 .chezmoiignore.tmpl
 .gitmodules
 .chezmoiscripts/
+  run_before_05-externals.sh.tmpl
   run_onchange_before_10-packages.sh.tmpl
   run_onchange_after_15-tools.sh.tmpl
   run_onchange_after_20-gh-extensions.sh.tmpl

docs/chezmoi/data.md

@@ -179,4 +179,4 @@ Every other YAML alias (`e`, `e.v`, `hx`, `cdc`, `cdk`, `cdl`, `cds`, `cdw`, and
 
 ## skills.yaml
 
-Declares the agent skills installed by the Skills CLI. `skills.cli` is the pinned CLI (`skills@1.7.0`, run with `npx -y`), `skills.agents` the default install targets (`[universal, claude-code]`), and `skills.sources` a list of `{ source, skills, agents? }` entries: 110 skills across 42 entries. The full list, pinned sources, and add/remove workflow are on the [Skills](../ai/skills.md) page.
+Declares where agent skills come from. `skills.cli` is the pinned CLI (`skills@1.7.0`, run with `npx -y`), `skills.agents` the install targets (`[universal, claude-code]`), and `skills.source` the single source, `prdlk/skills`: every skill in it is installed and skills from any other source are removed. See the [Skills](../ai/skills.md) page.

docs/chezmoi/externals-and-ignore.md

@@ -4,7 +4,7 @@ The git repos chezmoi clones into $HOME and every rule in .chezmoiignore.tmpl, i
 
 ## .chezmoiexternal.toml
 
-Externals are content chezmoi fetches instead of storing in the repo. Every entry is a `git-repo` external: chezmoi runs `git clone` when the target directory is missing. Because they are real git checkouts, they are never symlinked into the source tree.
+Externals are content chezmoi fetches instead of storing in the repo. Every entry is a `git-repo` external: chezmoi runs `git clone` when the target directory is missing. Because they are real git checkouts, they are never symlinked into the source tree. A target that already exists without being a checkout (Omarchy's stock `~/.config/kitty`, for example) would stop the apply; [`05-externals`](scripts.md#05-externals) asks to move it aside and clones the repo in its place first.
 
 **.chezmoiexternal.toml**
 

docs/chezmoi/scripts.md

@@ -2,50 +2,55 @@
 
 Every run_ script chezmoi executes during apply, when each one fires, and what it does on each OS and role.
 
-Seven scripts run during `chezmoi apply`. Five live in `.chezmoiscripts/`, a directory whose scripts run as if they sat at the source root without creating a matching target directory. Two sit at the repo root. All seven are templates; `20-gh-extensions` is a fish script, the rest use `#!/bin/sh` with `set -eu` (except `25-skills`, which uses `set -u`).
+Eight scripts run during `chezmoi apply`. Six live in `.chezmoiscripts/`, a directory whose scripts run as if they sat at the source root without creating a matching target directory. Two sit at the repo root. All eight are templates; `20-gh-extensions` is a fish script, the rest use `#!/bin/sh` with `set -eu` (except `25-skills`, which uses `set -u`).
 
 ## Execution order
 
 `before_` scripts run before any file is written; `after_` scripts run after every file, symlink, and external is in place. Within a phase chezmoi runs scripts in ASCII order of their target names, so the numeric prefixes come first.
 
-1. **10-packages (before, onchange)**
+1. **05-externals (before, every apply)**
+
+   Offer to replace external targets that exist but are not git checkouts.
+
+2. **10-packages (before, onchange)**
 
    Install system packages from `packages.yaml`.
 
-2. **Files, symlinks, externals**
+3. **Files, symlinks, externals**
 
    chezmoi writes the target state.
 
-3. **15-tools (after, onchange)**
+4. **15-tools (after, onchange)**
 
    rustup and cargo crates, omp, global mise tools, strata on Linux desktops.
 
-4. **20-gh-extensions (after, onchange)**
+5. **20-gh-extensions (after, onchange)**
 
    Install gh extensions from a fish session.
 
-5. **25-skills (after, onchange)**
+6. **25-skills (after, onchange)**
 
-   Install and prune agent skills.
+   Install every skill in prdlk/skills, remove skills from other sources.
 
-6. **30-user-services (after, once)**
+7. **30-user-services (after, once)**
 
    Enable systemd user units (kitty-day-save, projects-sync.timer).
 
-7. **40-post (after, onchange)**
+8. **40-post (after, onchange)**
 
    bat cache, font cache.
 
-8. **build-bat-cache (after, onchange)**
+9. **build-bat-cache (after, onchange)**
 
    Rebuild bat cache when its theme or config changes.
 
-9. **install-yazi-plugins (after, onchange)**
+10. **install-yazi-plugins (after, onchange)**
 
    Reinstall yazi plugins when the manifest changes.
 
 | Script | Phase | Frequency | Re-run trigger |
 | --- | --- | --- | --- |
+| `.chezmoiscripts/run_before_05-externals.sh.tmpl` | before | every apply | Always runs; cheap unless a target is in the way |
 | `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` | before | onchange | sha256 of `.chezmoidata/packages.yaml`; also the role and OS, which change the rendered package list |
 | `.chezmoiscripts/run_onchange_after_15-tools.sh.tmpl` | after | onchange | sha256 of `packages.shared.cargo` and `packages.shared.mise` as JSON; also the OS and role, which add the strata step |
 | `.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` | after | onchange | sha256 of `packages.shared.gh_extensions` as JSON |
@@ -63,6 +68,16 @@ Seven scripts run during `chezmoi apply`. Five live in `.chezmoiscripts/`, a dir
 
 `run_once_` scripts run once per unique rendered content and again only if that content changes or the previous run failed.
 
+## 05-externals
+
+`.chezmoiscripts/run_before_05-externals.sh.tmpl` clears the way for the `git-repo` externals in `.chezmoiexternals/*.toml` and `.chezmoiexternal.toml` (its list is rendered from those files, so new externals are covered without edits). chezmoi clones an external only into a missing or empty target and pulls only in an existing checkout; any other directory at the target stops the apply with a git error. A fresh Omarchy install ships its own `~/.config/kitty`, `ghostty`, `omarchy`, and others, so the first apply would stop there.
+
+- Runs before every apply (`run_before_`). With every target missing, empty, or already a checkout it only stats directories and exits 0.
+- For each target that exists otherwise (a non-empty directory without `.git`, a file, or a symlink), it asks on the terminal: `<target> exists and is not a git checkout. Replace it with <url> (old copy kept as <target>.bak-<time>)? [y/N]`.
+- **y**: moves the target to `<target>.bak-<YYYYmmdd-HHMMSS>` and runs `git clone <url> <target>`, so chezmoi finds a checkout and pulls. If the clone fails, the original is moved back and the script exits 1.
+- **n** (or anything else): exits 1 with a message, which aborts the apply; nothing is moved.
+- No terminal (`chezmoi apply` from a script or cron): lists the conflicting targets and exits 1.
+
 ## 10-packages
 
 `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` installs everything in [`packages.yaml`](data.md#packagesyaml). It runs before files are applied so the tools exist when configs land. On a non-Linux OS it renders to just the shebang and does nothing.
@@ -107,14 +122,13 @@ The strata flags install the binary, `~/.local/share/applications/io.github.lgse
 
 ## 25-skills
 
-`.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` installs the agent skills declared in [`skills.yaml`](data.md#skillsyaml) with the Skills CLI (`npx -y skills@1.7.0`). See [Skills](../ai/skills.md).
+`.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` installs every agent skill in the one source in [`skills.yaml`](data.md#skillsyaml), [prdlk/skills](https://github.com/prdlk/skills), with the Skills CLI (`npx -y skills@1.7.0`). See [Skills](../ai/skills.md).
 
-- Exits 0 with a warning if `npx` is missing.
-- One-time migration: deletes any directory in `~/.agents/skills` or `~/.claude/skills` that contains symlinks into the chezmoi source directory (the old vendored layout), and removes `~/.agents/.skill-lock.json` if it is a symlink into the source directory.
-- Removes skills listed in `${XDG_STATE_HOME:-~/.local/state}/chezmoi/skills.txt` that are no longer declared, with `skills remove -g -y`.
-- Runs one `skills add <source> -g -y -a <agents> --skill <names…>` per source entry. Output is captured; on failure the last 8 lines are printed.
-- Writes the declared names to `skills.txt`. Claude-only installs are not in the CLI's lock, so the script keeps its own record.
-- Exits 1 if any source failed, so chezmoi keeps the old hash and retries on the next apply.
+- Exits 0 with a warning if `npx` or `jq` is missing.
+- One-time migration: deletes any directory in `~/.agents/skills` or `~/.claude/skills` that contains symlinks into the chezmoi source directory (the old vendored layout), removes `~/.agents/.skill-lock.json` if it is a symlink into the source directory, and deletes the old state file `~/.local/state/chezmoi/skills.txt`.
+- Runs `skills add <source> -g -y -a <agents> --skill '*'`.
+- Reads the CLI's lock (`${XDG_STATE_HOME:-~/.local/state}/skills/.skill-lock.json`) and removes every skill whose recorded source is not `prdlk/skills`, with `skills remove -g -y`. Skills installed by packages are not in the lock and stay.
+- Exits 1 if the install or the removal failed, so chezmoi keeps the old hash and retries on the next apply. A failed install removes nothing.
 
 ## 30-user-services
 

docs/installation.md

@@ -84,7 +84,7 @@ See [Configuration](chezmoi/config.md) for how the role is stored and [Ignore ru
 
 3. **Files and externals**
 
-   Configs are linked into `$HOME` (symlink mode). The neovim config, Omarchy's `~/.config/omarchy` checkout, and the terminal and tool configs are cloned as externals. See [Externals and ignore rules](chezmoi/externals-and-ignore.md).
+   Configs are linked into `$HOME` (symlink mode). The neovim config, Omarchy's `~/.config/omarchy` checkout, and the terminal and tool configs are cloned as externals. Where Omarchy already put a directory at one of those paths, `run_before_05-externals` asks whether to replace it (the old copy is kept as `<dir>.bak-<time>`); answering no aborts the apply. See [Externals and ignore rules](chezmoi/externals-and-ignore.md).
 
 4. **Post-apply scripts**