本地智能体能力调度系统：基于npx+manifest.json的CLI技能架构-平芜编程栈

1. 项目概述：这不是一个“技能库”，而是一套可执行的智能体能力调度系统

你搜“skills”时看到的满屏关键词——claude code、npx、bash、setup-matt-pocock-skills、playwright install失败、git bash复制粘贴、vscode配置、本地模型调用……这些不是零散的工具名，而是一个正在快速成型的开发者新工作流信号。它指向的不是某个静态的“技能清单”，而是一套以 CLI 为入口、以 npm 包为载体、以本地终端为执行沙盒、以 LLM 为决策中枢的可编程能力调度系统。我从去年底开始深度参与多个内部 agent 工具链建设，从最初手动写 shell 脚本调用 curl，到如今用npx @matt-pocock/skills一行命令拉起整套环境，踩过至少 17 个不同系统的坑——Windows 的权限锁死、macOS 的 SIP 干预、Ubuntu 的 snap 包冲突、WSL2 的 systemd 缺失、Git Bash 的 POSIX 兼容断层……这些都不是“安装失败”的借口，而是系统级能力调度必须直面的真实边界。

所谓“skills”，本质是把传统意义上需要人工判断、组合、执行的开发动作（比如“查 Git 提交历史 → 找出最近三次 PR 的作者 → 检查他们提交的 package.json 变更 → 输出依赖风险报告”），封装成带明确输入/输出契约、可被 LLM 理解并调用的独立可执行单元。它不依赖云端 API 密钥（虽然支持），也不强制绑定某家大模型（Claude、DeepSeek、Qwen、GLM 都能接入），核心逻辑全部跑在你本地终端里。你敲下npx skills list，它不是去远程服务器查数据库，而是扫描你当前目录下的skills/文件夹，读取每个子目录里的manifest.json和run.sh；你运行npx skills test --name=git-diff-analyze，它实际执行的是bash -c "cd ./skills/git-diff-analyze && ./run.sh --commit-hash=HEAD~2"。整个过程没有中间代理、没有网络跳转、没有后台服务——只有你的终端、你的文件系统、你的 shell 解释器。

这解释了为什么“git bash 安装”和“bash: screen: command not found”会高频共现：Git Bash 是 Windows 上最接近 POSIX 标准的轻量终端，但它默认不带screen、jq、yq、fzf这些 skills 生态链必备的 CLI 工具；而npx playwright install 失败的根因，往往不是 Playwright 本身的问题，而是 skills 脚本在执行前检测到which chromium返回空，于是自动触发npx playwright install --with-deps，结果在 Git Bash 下--with-deps参数被错误解析，最终卡在apt-get update步骤——因为 Git Bash 根本没有 apt。所以，“skills”不是让你学一堆新命令，而是教你重新理解：终端是什么？脚本的本质是什么？LLM 在本地能真正控制什么？当你明白bash -c "$(curl -fsSL $(echo dmftlmluay8wmg== | base64 --decode))"这行看似玄学的命令，其实只是把 base64 解码后的 GitHub raw URL（比如https://raw.githubusercontent.com/matt-pocock/skills/main/install.sh）喂给 bash 执行，你就跨过了第一个认知门槛。这套系统真正的门槛，从来不在模型多大、API 多快，而在你是否愿意把终端当作第一开发界面，而非仅仅是个输出日志的窗口。

2. 核心设计逻辑与底层架构拆解

2.1 为什么选择 npx 作为统一入口？而不是 CLI 全局安装或 Docker？

很多人第一反应是：“为什么不直接npm install -g @matt-pocock/skills？” 或者 “Docker 不是更隔离吗？” 这背后是经过至少三轮架构迭代后确定的硬性约束。我们团队在 2023 年 Q3 做过对比测试：在 12 种主流开发环境（Win10/11 + WSL1/2 + Git Bash / macOS Monterey/Ventura/Sonoma / Ubuntu 20.04/22.04/24.04 / Fedora 38/39）上，全局安装 CLI 的失败率高达 43%，主要集中在三类问题：

权限撕裂：Windows 上 npm 全局安装路径常落在C:\Users\XXX\AppData\Roaming\npm，而 VS Code 的集成终端默认以普通用户身份启动，但某些 skills（如涉及sudo apt install的）又要求 root 权限，导致权限链断裂；
版本污染：全局安装意味着所有项目共享同一套 skills runtime，当 A 项目依赖@skills/core v1.2，B 项目需要v2.0（含 breaking change），全局 CLI 无法同时满足；
环境不可知：Docker 虽然隔离，但 skills 的核心价值在于与本地开发环境深度耦合——它要读取你.git/config里的 remote URL，要解析pnpm-lock.yaml里的包哈希，要调用你本地 VS Code 的code --list-extensions，这些操作在容器内要么失效，要么需要复杂挂载。

npx 的解法极其朴素：每次执行都临时下载、解压、执行、清理。npx @matt-pocock/skills@latest list实际流程是：

npx检查本地node_modules/.bin/skills是否存在且版本匹配；
若不匹配，则从 npm registry 下载@matt-pocock/skillstarball（约 8.2MB）；
解压到临时目录（如/tmp/npx-abc123），其中包含bin/skills.js和dist/skills-core.js；
skills.js启动后，立即读取当前工作目录下的skills/子目录结构，构建能力索引；
执行完毕，npx自动清理/tmp/npx-abc123（除非显式加--no-cleanup）。

这个设计带来三个关键收益：

零污染：每个命令都是干净沙盒，A 项目npx skills run --name=pr-review和 B 项目npx skills run --name=dep-audit互不影响；
版本精确：npx @matt-pocock/skills@1.3.5 list强制锁定版本，避免 CI/CD 中因latest变动导致行为漂移；
跨平台兜底：即使用户没装 Node.js，npx会自动 fallback 到npx.dev的 CDN 执行（需网络），这是 npm 8.0+ 内置能力。

提示：npx不是魔法，它依赖node和npm的基础存在。如果你的which node返回空，npx必然失败。此时应先解决 Node.js 环境问题，而非怪 skills 不兼容——这是基础设施层，不是 skills 层的责任。

2.2 skills 目录结构为何强制要求 manifest.json + run.sh？而不是单一 JS 文件？

你可能见过很多 CLI 工具用纯 JavaScript 实现（如create-react-app），为什么 skills 坚持用manifest.json+run.sh的双文件结构？答案藏在“可审计性”和“跨语言兼容性”里。

manifest.json是 skills 的“宪法”，定义其元数据契约：

{ "name": "git-diff-analyze", "version": "0.2.1", "description": "分析指定 commit 的代码变更，识别高风险模式", "input": { "commit-hash": { "type": "string", "required": true, "default": "HEAD" }, "threshold-lines": { "type": "number", "required": false, "default": 50 } }, "output": { "risk-level": "high|medium|low", "changed-files": ["string"], "suspicious-patterns": ["string"] }, "requires": ["git", "grep", "awk", "jq"], "runtime": "bash" }

这个文件强制声明了：它需要哪些系统命令（requires）、接受什么参数（input）、返回什么结构（output）、用什么解释器执行（runtime）。LLM 在调用前，会先 parse 这个 JSON，验证输入参数类型是否匹配（比如传入字符串"100"给threshold-lines数字字段，会被拒绝），再检查which git grep awk jq是否全部存在——所有校验都在执行前完成，而非在脚本里用if ! command -v git; then exit 1; fi这种事后补救。

run.sh则是纯粹的执行体，它不处理任何参数校验、不关心输出格式、不做错误重试——它的唯一职责是：拿到manifest.json里定义的参数，执行具体逻辑，并按约定格式echoJSON 输出。例如：

#!/usr/bin/env bash # run.sh for git-diff-analyze set -euo pipefail COMMIT_HASH="${1:-HEAD}" THRESHOLD_LINES="${2:-50}" # 核心逻辑：只做一件事——提取变更文件并扫描风险模式 CHANGED_FILES=$(git diff-tree --no-commit-id --name-only -r "$COMMIT_HASH" | grep -E '\.(js|ts|jsx|tsx)$') RISK_LEVEL="low" SUSPICIOUS_PATTERNS=() while IFS= read -r file; do if [ -f "$file" ]; then # 检查是否新增 eval() 或 with() if grep -qE 'eval\s*\(|with\s*\(' "$file"; then SUSPICIOUS_PATTERNS+=("eval/with in $file") RISK_LEVEL="high" fi # 检查是否修改超过阈值行数 LINES_CHANGED=$(git diff "$COMMIT_HASH^" "$COMMIT_HASH" -- "$file" | wc -l) if [ "$LINES_CHANGED" -gt "$THRESHOLD_LINES" ]; then SUSPICIOUS_PATTERNS+=("large change in $file ($LINES_CHANGED lines)") RISK_LEVEL="medium" fi fi done <<< "$CHANGED_FILES" # 严格按 manifest.output 格式输出 JSON jq -n \ --arg risk "$RISK_LEVEL" \ --argjson files "[$(printf '%s\n' $CHANGED_FILES | jq -R . | jq -s)]" \ --argjson patterns "[$(printf '%s\n' "${SUSPICIOUS_PATTERNS[@]}" | jq -R . | jq -s)]" \ '{ "risk-level": $risk, "changed-files": $files, "suspicious-patterns": $patterns }'

这种分离带来的好处是颠覆性的：

LLM 可推理：模型看到manifest.json就知道这个 skill 能做什么、要什么、返回什么，无需阅读 bash 脚本；
人类可审计：运维人员只需看manifest.json就能确认该 skill 是否符合安全策略（比如requires里不能有sudo）；
未来可扩展：runtime字段支持"python"、"deno"、"rust"，只要对应解释器存在，skills 系统就能调用——我们已在内部 PoC 中用runtime: deno实现了基于 Deno Deploy 的无服务器技能。

2.3 Claude Code 与 skills 的关系：不是替代，而是协同增强

搜索热词里大量出现 “Claude Code”、“Claude Code 安装”、“Claude Code 调用 lmstudio”，这反映出一个普遍误解：认为 skills 是 Claude Code 的竞品。事实恰恰相反——skills 是让 Claude Code 真正落地的“肌肉组织”。

Claude Code 的核心能力是“理解上下文 + 生成代码”，但它缺乏“执行”和“反馈闭环”。当你在 VS Code 里对一段代码按Cmd+K，Claude Code 可能建议：“你可以用git diff --name-only HEAD~1获取变更文件”。但接下来呢？你需要手动复制命令、切换终端、粘贴执行、再回到编辑器看结果——这个“执行鸿沟”让 73% 的建议停留在理论层面。

skills 填补了这个鸿沟。VS Code 插件（如skills-vscode）会在 Claude Code 的响应中注入特殊标记：

> 🧠 建议：运行 `skills run --name=git-diff-analyze --commit-hash=HEAD~1` 获取风险报告 > ⚙️ 执行：[点击运行]（按钮触发 `npx skills run --name=git-diff-analyze --commit-hash=HEAD~1`） > 📊 结果：{ "risk-level": "medium", "changed-files": ["src/utils/date.ts"], "suspicious-patterns": ["large change in src/utils/date.ts (87 lines)"] }

这个流程的关键在于：skills 的输出是结构化 JSON，而非纯文本日志。VS Code 插件能直接 parse 这个 JSON，将risk-level渲染为颜色徽章，将changed-files显示为可点击的文件链接，将suspicious-patterns生成 CodeLens 快捷操作（如“跳转到该行”）。Claude Code 提供“大脑”，skills 提供“手和眼”，二者结合才构成完整智能体。

这也解释了为什么 “vscode 配置 claude code” 和 “ubuntu 配置 claude code” 会成为高频问题——配置难点从来不在 Claude Code 本身，而在如何让它的输出能被本地 skills 系统消费。典型配置项包括：

在 VS Codesettings.json中设置"skills.executable": "npx @matt-pocock/skills"；
确保PATH包含npm config get prefix下的bin目录（否则npx找不到）；
为 Ubuntu 用户额外安装jq和yq（sudo apt install jq yq），因为 skills 的 JSON 处理重度依赖它们。

3. 实操全流程：从零搭建可运行的 skills 环境

3.1 环境准备：绕过 90% 的安装失败陷阱

“npx playwright install 失败”、“bash: screen: command not found” 这些报错，90% 源于环境准备阶段的三个隐形假设被打破。我们必须主动打破它们：

假设一：你的终端能运行标准 POSIX 命令
现实：Git Bash 默认不带screen、fzf、yq；WSL2 的 Ubuntu 默认不带jq；macOS 的 Terminal 默认不带gnu-sed。
解决方案：一次性安装所有 skills 生态依赖：

# macOS (使用 Homebrew) brew install jq yq fzf gnu-sed --with-default-names # Ubuntu/Debian sudo apt update && sudo apt install -y jq yq fzf # Windows + Git Bash (需先安装 Chocolatey) # 在管理员 PowerShell 中执行： Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) # 然后在 Git Bash 中： choco install jq yq fzf # WSL2 Ubuntu (若 apt 报错，先修复) sudo rm /var/lib/dpkg/info/*.list sudo dpkg --configure -a sudo apt clean sudo apt update && sudo apt install -y jq yq fzf

注意：--with-default-names对gnu-sed至关重要，否则sed命令在 macOS 上会因 BSD vs GNU 语法差异而失败。skills 脚本中大量使用-i ''参数（GNU 风格），没有此 flag 会报错。

假设二：Node.js 版本足够新
现实：skills 最低要求 Node.js v18.17.0（因依赖fetchAPI 和stream/web）。许多企业电脑仍停留在 v14.x。
验证命令：node -v。若低于 v18.17.0，不要用 nvm install（nvm 在 Git Bash 下常出问题），改用官方二进制：

macOS：下载.pkg安装包，运行即可；
Windows：从 nodejs.org 下载.msi，勾选 “Add to PATH”；
Ubuntu：curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs。

假设三：网络能直达 npm registry
现实：国内用户常遇到npx卡在Downloading ...。这不是 skills 的问题，而是 npm 源问题。
永久解决方案（非临时镜像）：

# 设置 npm registry 为中国镜像（阿里云） npm config set registry https://registry.npmmirror.com # 验证 npm config get registry # 应输出 https://registry.npmmirror.com # 清理 npx 缓存（关键！） npx clear-npx-cache # 测试 skills 基础功能 npx @matt-pocock/skills@latest --help

提示：clear-npx-cache是 npm 8.12+ 内置命令，它会删除~/.npm/_npx/下所有缓存。很多“安装失败”其实是旧缓存损坏导致的，清缓存比重装更有效。

3.2 初始化 skills 目录：创建你的第一个可执行能力

skills 的核心目录./skills/必须手动创建，npx不会自动帮你建。这是刻意设计——它迫使你意识到：能力是你自己定义的，不是框架赋予的。

步骤详解（以创建hello-worldskill 为例）：

在项目根目录创建skills/文件夹：
```
mkdir -p skills/hello-world
```

编写skills/hello-world/manifest.json：

{ "name": "hello-world", "version": "0.1.0", "description": "最简技能：打印问候语", "input": { "name": { "type": "string", "required": true, "default": "World" } }, "output": { "message": "string", "timestamp": "string" }, "requires": [], "runtime": "bash" }

关键点：requires为空数组，表示不依赖外部命令；input.name设为required，调用时必须传参。

编写skills/hello-world/run.sh：

#!/usr/bin/env bash set -euo pipefail NAME="${1:-World}" # 严格按 output 格式输出 JSON jq -n \ --arg msg "Hello, $NAME!" \ --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ '{ "message": $msg, "timestamp": $ts }'

注意：#!/usr/bin/env bash是必须的 shebang；set -euo pipefail是错误处理基石；jq -n生成 JSON，避免手动拼接引号错误。

赋予执行权限（Windows Git Bash 也需）：
```
chmod +x skills/hello-world/run.sh
```

测试执行：

npx @matt-pocock/skills@latest run --name=hello-world --name=SkillsEngineer # 输出：{"message":"Hello, SkillsEngineer!","timestamp":"2024-06-15T08:23:45Z"}

这个过程看似简单，却埋着三个实操心得：

JSON 输出必须合法：jq -n是唯一推荐方式。曾有人用echo "{\"message\":\"$NAME\"}"，当$NAME包含单引号时直接 JSON 解析失败；
参数传递要严谨：run.sh的$1对应--name=xxx的值，$2对应下一个参数。skills 系统不解析--flag=value，只按位置传参；
时间戳用 UTC：date -u避免时区混乱，所有 skills 输出的时间字段必须统一时区，否则聚合分析会出错。

3.3 集成 Playwright：解决 “npx playwright install 失败” 的根本方案

“npx playwright install 失败” 是 skills 新手最高频问题，根源在于 skills 的playwright-testskill 在执行前会自动检测浏览器环境，若缺失则触发npx playwright install。但在 Git Bash 或 WSL2 下，这个命令常因权限或依赖缺失而中断。

正确做法不是硬刚npx playwright install，而是预装 Playwright 并配置 skills 跳过自动安装：

全局安装 Playwright（一次搞定）：

# 确保已安装依赖 sudo apt install -y libgbm1 libasound2 libatk1.0-0 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxdmcp1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libatspi2.0-0 libcairo2 libdrm2 libgbm1 libglib2.0-0 libgtk-3-0 libkrb5-3 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxdmcp1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 # 安装 Playwright npm install -g playwright npx playwright install chromium firefox webkit

创建skills/playwright-test/manifest.json，关键加入skip-install: true：

{ "name": "playwright-test", "version": "0.3.0", "description": "运行 Playwright E2E 测试", "input": { "test-file": { "type": "string", "required": true }, "browser": { "type": "string", "required": false, "default": "chromium" } }, "output": { "status": "passed|failed|skipped", "duration-ms": "number", "error-message": "string" }, "requires": ["npx", "playwright"], "runtime": "bash", "config": { "skip-install": true } }

run.sh中直接调用npx playwright test，不再检查浏览器：

#!/usr/bin/env bash set -euo pipefail TEST_FILE="${1}" BROWSER="${2:-chromium}" # 直接运行，信任预装环境 npx playwright test "$TEST_FILE" --browser="$BROWSER" --workers=1 2>&1 | \ jq -n --argjson result "$(cat)" \ '{ "status": if $result | contains("OK") then "passed" elif $result | contains("FAIL") then "failed" else "skipped" end, "duration-ms": 0, "error-message": $result }'

这样做的优势：安装一次，永久生效；skills 调用时秒级启动，无网络等待；失败时错误信息清晰指向测试代码，而非npx install的底层依赖。

3.4 连接本地大模型：用 LMStudio 调用 Qwen，绕过 Claude 订阅限制

热词中反复出现 “claude 国内安装 skills 官方市场”、“your organization has disabled claude subscription access”，这暴露了一个现实：skills 的价值不绑定任何特定模型。我们完全可以用 LMStudio 加载 Qwen2-7B，让 skills 调用它。

步骤（以 LMStudio + Qwen2-7B 为例）：

下载 LMStudio，加载Qwen2-7B-Instruct-Q4_K_M.gguf模型，启动本地 server（默认http://localhost:1234/v1）；

创建skills/lmstudio-chat/manifest.json：

{ "name": "lmstudio-chat", "version": "0.1.0", "description": "调用本地 LMStudio 的 Qwen 模型", "input": { "prompt": { "type": "string", "required": true }, "temperature": { "type": "number", "required": false, "default": 0.7 } }, "output": { "response": "string", "model": "string", "tokens-used": "number" }, "requires": ["curl", "jq"], "runtime": "bash" }

run.sh实现 HTTP 调用：

#!/usr/bin/env bash set -euo pipefail PROMPT="${1}" TEMP="${2:-0.7}" # 调用 LMStudio API RESPONSE=$(curl -s -X POST http://localhost:1234/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "'"$PROMPT"'"}], "model": "Qwen2-7B-Instruct", "temperature": '"$TEMP"' }' | jq -r '.choices[0].message.content') # 统计 token（简化版，实际需调用 tokenizer） TOKENS=$(echo "$PROMPT" | wc -w) jq -n \ --arg resp "$RESPONSE" \ --arg model "Qwen2-7B-Instruct" \ --argjson tokens "$TOKENS" \ '{ "response": $resp, "model": $model, "tokens-used": $tokens }'

测试：

npx @matt-pocock/skills@latest run --name=lmstudio-chat --prompt="用 TypeScript 写一个深拷贝函数"

这个方案彻底摆脱了 Claude 订阅限制，且响应速度更快（本地 GPU 推理 vs 网络 API）。关键是，skills 的manifest.json定义了输入输出契约，LLM 只需理解这个契约，就能调度它——无论背后是 Claude、Qwen 还是 GLM。

4. 常见问题与排查技巧实录

4.1 “bash: screen: command not found” —— 不是 bug，是设计意图

这个报错在 Windows Git Bash 和 macOS 上高频出现，但很少人意识到：skills 系统故意不依赖screen。screen是用于会话管理的工具，而 skills 的设计哲学是“每个命令都是原子性、幂等性、短生命周期的”。npx skills run执行完就退出，不存在“保持会话”的需求。

那么为什么报错？因为某些第三方 skills（如docker-compose-up）在run.sh里写了screen -S docker-compose -d -m docker-compose up。这是对 skills 架构的误用。正确解法只有两个：

方案一（推荐）：改写run.sh，去掉screen，直接用docker-compose up -d后台启动，skills 只负责启动，不管理生命周期；
方案二（兜底）：在 Git Bash 中安装screen（choco install screen），但这违背了 skills 的轻量原则。

实操心得：我曾帮一个金融客户排查此问题，发现他们 80% 的screen依赖源于一个过时的skills-template。最终方案是用systemd-run --scope（Linux）或start /B（Windows）替代screen，既满足后台需求，又不引入新依赖。

4.2 “npx playwright install 失败” 的五层排查法

当npx playwright install卡住，按以下顺序逐层排查（每层耗时 < 2 分钟）：

层级	检查命令	预期输出	问题定位	解决方案
L1：网络连通性	`curl -I https://npmmirror.com`	`HTTP/2 200`	DNS 或防火墙拦截	`export HTTPS_PROXY=http://127.0.0.1:7890`（若用代理）
L2：npm 权限	`npm config get prefix`	`/home/user/.nvm/versions/node/v18.17.0`	权限不足导致写入失败	`sudo chown -R $USER:$USER $(npm config get prefix)`
L3：磁盘空间	`df -h`	`/dev/sda1 95%`	空间不足无法下载 Chromium	`sudo apt clean && rm -rf ~/.cache/playwright`
L4：依赖缺失	`ldd $(which chromium-browser) \| grep "not found"`	`libgbm.so.1 => not found`	系统库缺失	`sudo apt install -y libgbm1 libasound2 ...`（见 3.3 节）
L5：Git Bash 兼容性	`which apt`	空	Git Bash 无 apt，不能用`--with-deps`	改用`npx playwright install chromium`（不带 deps）

注意：L5 是 Windows 用户专属陷阱。Git Bash 没有apt，所以npx playwright install --with-deps必然失败。解决方案是：在 Windows Subsystem for Linux (WSL) 中安装 Playwright，然后在 Git Bash 中通过wsl.exe调用，或直接放弃--with-deps，手动安装 Chromium。

4.3 VS Code 集成失败：为什么 “Claude Code 调用 skills” 没反应？

VS Code 插件显示 “Skills ready”，但 Claude Code 的建议里没有[点击运行]按钮。这通常由三个原因导致：

原因一：插件未启用 skills 支持

打开 VS Code 设置（Cmd+,），搜索skills；
确认Skills: Enabled为true；
检查Skills: Executable Path是否为npx @matt-pocock/skills（不是skills）。

原因二：当前文件不在 skills 可见范围内
skills 插件只扫描打开的文件所在文件夹及其父级的skills/目录。如果skills/在~/projects/my-app/，而你打开的是~/projects/my-app/src/index.ts，则可见；但如果打开~/temp/test.ts，则不可见。
解决方案：在 VS Code 中File > Open Folder...，选择包含skills/的根目录。

原因三：Claude Code 的响应未被 skills 插件识别
skills 插件通过正则匹配 Claude Code 的输出，寻找skills run --name=模式。如果 Claude Code 生成的是npx skills run --name=xxx，插件会忽略（因npx前缀）。
解决方案：在 VS Code 设置中，将Skills: Command Prefix设为npx skills，或让 Claude Code 生成不带npx的命令。

实操心得：我们内部用skills-vscode的 debug 模式（Developer: Toggle Developer Tools→ Console）查看日志，发现 60% 的“无反应”问题源于路径未匹配。一个简单技巧：在项目根目录放一个空的skills/.enabled文件，插件会优先扫描该目录。

4.4 安卓脱壳 skills 的可行性分析：为什么这不是 skills 的设计场景？

热词中出现 “安卓脱壳 skills”，这反映了对 skills 能力边界的误判。skills 的设计目标是辅助开发者提升日常编码效率，而非逆向工程工具。原因有三：

权限限制：安卓脱壳需 root 权限、ADB 调试开启、frida-server 注入等，这些操作远超 skills 的requires能力范围（skills 只能调用adb，但无法保证设备已 root）；
环境不可控：脱壳需特定手机型号、Android 版本、厂商定制 ROM，skills 无法在 manifest 中声明这些硬件依赖；
法律风险：未经许可的脱壳违反《计算机软件保护条例》，skills 社区明确禁止此类用途。

如果你真有脱壳需求，正确路径是：