diff --git a/docs/ai/skills.mdx b/docs/ai/skills.mdx
index 7e03e96..f0879f6 100644
--- a/docs/ai/skills.mdx
+++ b/docs/ai/skills.mdx
@@ -21,11 +21,13 @@ Skills are installed and updated with the Skills CLI (`npx skills`), which the `
 
 ```sh
 npx skills find <query>            # search the registry
-npx skills add <owner/repo@skill> -g -y   # install at user level
+npx skills add <owner/repo@skill> -g -y -a universal claude-code   # install at user level
 npx skills check                   # look for updates
 npx skills update                  # update everything
 ```
 
+Always pass `-a universal claude-code` to `add`. Without an explicit agent list, skills CLI 1.7.0 adds every `.agents/skills` agent to the install targets, including PromptScript, which has no global skills directory. The skill still lands in `~/.agents/skills`, but the run ends with `✗ <skill> → PromptScript: PromptScript does not support global skill installation` (upstream [vercel-labs/skills#1496](https://github.com/vercel-labs/skills/issues/1496)).
+
 A skill installed this way lands in `~/.agents/skills/<name>/` as plain files. Add it to the repo with `chezmoi add ~/.agents/skills/<name>`, and commit the updated `.skill-lock.json` alongside it. To expose it to Claude Code, add a `dot_claude/skills/symlink_<name>` file containing `../../.agents/skills/<name>`.
 
 ### .skill-lock.json