docs(docs): clarify skills sync workflow in documentation

docs/chezmoi/data.mdx

@@ -9,6 +9,7 @@ Files in `.chezmoidata/` are merged into chezmoi's template data on every run. N
 | --- | --- | --- |
 | `.chezmoidata/packages.yaml` | `.packages` | [`run_onchange_before_10-packages.sh.tmpl`](/chezmoi/scripts#10-packages), [`run_onchange_after_20-gh-extensions.sh.tmpl`](/chezmoi/scripts#20-gh-extensions) |
 | `.chezmoidata/aliases.yaml` | `.aliases` | `dot_config/shell/aliases.sh.tmpl` (bash and zsh) |
+| `.chezmoidata/skills.yaml` | `.skills` | [`run_onchange_after_25-skills.sh.tmpl`](/chezmoi/scripts#25-skills) |
 
 ## packages.yaml [#packagesyaml]
 
@@ -187,3 +188,7 @@ Every other YAML alias (`e`, `e.v`, `hx`, `cdc`, `cdk`, `cdl`, `cds`, `cdw`, and
 :::tip
 To add an alias for every shell, add it to `aliases.yaml` for bash/zsh and to `20-aliases.fish` by hand for fish.
 :::
+
+## skills.yaml [#skillsyaml]
+
+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) page.

docs/chezmoi/index.mdx

@@ -25,11 +25,13 @@ The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/.lo
 - .chezmoidata/
   - aliases.yaml
   - packages.yaml
+  - skills.yaml
 - .chezmoiexternal.toml
 - .chezmoiignore.tmpl
 - .chezmoiscripts/
   - run_onchange_before_10-packages.sh.tmpl
   - run_onchange_after_20-gh-extensions.sh.tmpl
+  - run_onchange_after_25-skills.sh.tmpl
   - run_once_after_30-user-services.sh.tmpl
   - run_onchange_after_40-post.sh.tmpl
 - run_onchange_after_build-bat-cache.sh.tmpl
@@ -67,12 +69,8 @@ The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/.lo
 - dot_claude/
   - commands/
   - hooks/
-  - skills/
   - settings.json
   - empty_CLAUDE.md
-- dot_agents/
-  - skills/
-  - dot_skill-lock.json
 - dot_omp/
   - loops/
   - private_agent/
@@ -89,14 +87,13 @@ The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/.lo
 | Path | Target | Purpose |
 | --- | --- | --- |
 | `.chezmoi.toml.tmpl` | `~/.config/chezmoi/chezmoi.toml` | Config template rendered by `chezmoi init`. See [Config and roles](/chezmoi/config). |
-| `.chezmoidata/` | — | YAML merged into template data (`.packages`, `.aliases`). See [Packages and aliases](/chezmoi/data). |
+| `.chezmoidata/` | — | YAML merged into template data (`.packages`, `.aliases`, `.skills`). See [Packages and aliases](/chezmoi/data) and [Skills](/ai/skills). |
 | `.chezmoiexternal.toml` | — | Git repos cloned into `$HOME` (nvim config, a bat syntax). |
 | `.chezmoiignore.tmpl` | — | Target paths chezmoi skips; gates the Linux desktop layer by role. |
 | `.chezmoiscripts/`, root `run_*` | — | Install and housekeeping scripts. See [Apply scripts](/chezmoi/scripts). |
 | `dot_config/` | `~/.config/` | Per-tool config. Documented under [Shell](/shell), [Terminal](/terminal), [Tools](/tools), [Desktop](/desktop). |
 | `dot_local/bin/` | `~/.local/bin/` | 33 standalone scripts shared by every shell. |
-| `dot_claude/` | `~/.claude/` | Claude Code settings, commands, hooks, and skill symlinks. See [AI agents](/ai/claude-code). |
-| `dot_agents/` | `~/.agents/` | The shared agent skill library the `~/.claude/skills` symlinks resolve against. |
+| `dot_claude/` | `~/.claude/` | Claude Code settings, commands, and hooks. See [AI agents](/ai/claude-code). |
 | `dot_omp/` | `~/.omp/` | omp agent config and loops. |
 | `dot_leetcode/` | `~/.leetcode/` | leetcode CLI workspace state. |
 | `docs/`, `public/`, `blume.config.ts`, `package.json`, `bun.lock`, `README.md` | — | This docs site and the repo README. Listed in `.chezmoiignore.tmpl`, never applied. |
@@ -109,12 +106,12 @@ chezmoi encodes target names and attributes in source file names. These are the
 
 | Source form | Meaning | Examples here |
 | --- | --- | --- |
-| `dot_` | Target name starts with `.` | `dot_config` → `~/.config`, `dot_zshrc` → `~/.zshrc`, `dot_skill-lock.json` → `.skill-lock.json` |
+| `dot_` | Target name starts with `.` | `dot_config` → `~/.config`, `dot_zshrc` → `~/.zshrc` |
 | `private_` | Target has group/world permissions cleared (`0600`/`0700`) | `dot_config/atuin/private_config.toml`, `dot_config/gh/private_config.yml`, `dot_config/hunk/private_state.json`, `dot_omp/private_agent/`, `dot_omp/loops/*/private_loop.md` |
-| `executable_` | Target gets the executable bit | 49 files: every script in `dot_local/bin/`, `dot_config/niri/scripts/`, `dot_config/tmux/executable_niri-title.sh`, Claude hooks, skill helper scripts |
+| `executable_` | Target gets the executable bit | 42 files: every script in `dot_local/bin/`, `dot_config/niri/scripts/`, `dot_config/tmux/executable_niri-title.sh`, Claude hooks, `dot_omp/loops/bin/executable_run-loop.sh` |
 | `exact_` | Directory is exact: entries in the target that are not in the source are deleted | `dot_config/niri/exact_config.d/` (numbered `10-…kdl` through `95-…kdl` fragments) |
 | `empty_` | File is kept even when empty | `dot_claude/empty_CLAUDE.md`, `dot_config/herdr/empty_dot_plugins.lock` |
-| `symlink_` | Target is a symlink; file content is the link destination | 67 entries in `dot_claude/skills/` (each → `../../.agents/skills/<name>`), `dot_config/kitty/symlink_current-theme.conf` (→ `themes/noctalia.conf`) |
+| `symlink_` | Target is a symlink; file content is the link destination | `dot_config/kitty/symlink_current-theme.conf` (→ `themes/noctalia.conf`), `dot_config/symlink_television.tmpl` |
 | `.tmpl` | Rendered with Go templates and chezmoi data | `dot_gitconfig.tmpl`, `dot_config/shell/aliases.sh.tmpl`, `dot_config/yazi/yazi.toml.tmpl`, all scripts, the config and ignore files |
 | `run_once_` / `run_onchange_` + `before_` / `after_` | Script, with run frequency and phase | See [Apply scripts](/chezmoi/scripts) |
 

docs/chezmoi/scripts.mdx

@@ -13,6 +13,7 @@ Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a direc
   <Step title="10-packages (before, onchange)">Install system packages from `packages.yaml`.</Step>
   <Step title="Files, symlinks, externals">chezmoi writes the target state.</Step>
   <Step title="20-gh-extensions (after, onchange)">Install gh extensions.</Step>
+  <Step title="25-skills (after, onchange)">Install and prune agent skills.</Step>
   <Step title="30-user-services (after, once)">Enable systemd user units on Linux.</Step>
   <Step title="40-post (after, onchange)">tpm clone, bat cache, font cache.</Step>
   <Step title="build-bat-cache (after, onchange)">Rebuild bat cache when its theme or config changes.</Step>
@@ -23,6 +24,7 @@ Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a direc
 | --- | --- | --- | --- |
 | `.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_20-gh-extensions.sh.tmpl` | after | onchange | sha256 of `packages.shared.gh_extensions` as JSON |
+| `.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` | after | onchange | sha256 of `.skills` as JSON |
 | `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` | after | once | Runs once per distinct rendered content |
 | `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` | after | onchange | Only edits to the script itself (or an OS change) |
 | `run_onchange_after_build-bat-cache.sh.tmpl` | after | onchange | sha256 of `dot_config/bat/themes/cyberdream.tmTheme` and `dot_config/bat/config` |
@@ -75,6 +77,17 @@ On any other OS the script renders to just the shebang and comments and does not
 A skipped run still exits 0, so chezmoi records this content as done and a plain re-apply does not retry it, despite what the warning text says. After `gh auth login`, either run `gh extension install` for each entry by hand, or clear chezmoi's onchange state with `chezmoi state delete-bucket --bucket=entryState` and apply again (this re-runs every `run_onchange_` script).
 :::
 
+## 25-skills [#25-skills]
+
+`.chezmoiscripts/run_onchange_after_25-skills.sh.tmpl` installs the agent skills declared in [`skills.yaml`](/chezmoi/data#skillsyaml) with the Skills CLI (`npx -y skills@1.7.0`). See [Skills](/ai/skills).
+
+- 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.
+
 ## 30-user-services [#30-user-services]
 
 `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` enables session-critical systemd user units on Linux.