docs(docs): clarify skills sync workflow in documentation

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.