Agent Skills Scanner

扫描本机和项目里的主流 Agent SKILL.md，生成可搜索的 HTML 报告，也支持 JSON 输出。

默认扫描范围

默认只扫描 P0 级别端上的 Skills，不扫描 rules、instructions、workflows、commands 等其他配置资产。

用户级：

• Trae: ~/.trae/**/SKILL.md
• Trae CN: ~/.trae-cn/**/SKILL.md
• Agents: ~/.agents/**/SKILL.md
• Claude Code: ~/.claude/**/SKILL.md
• GitHub Copilot / VS Code: ~/.copilot/**/SKILL.md
• Cursor: ~/.cursor/**/SKILL.md
• Codex: ~/.codex/**/SKILL.md
• Windsurf: ~/.codeium/windsurf/**/SKILL.md

项目级：

• .trae/**/SKILL.md
• .trae-cn/**/SKILL.md
• .agents/**/SKILL.md
• .claude/**/SKILL.md
• .github/skills/**/SKILL.md
• .cursor/**/SKILL.md
• .codex/**/SKILL.md
• .windsurf/**/SKILL.md

项目级扫描会先在 --code-root 下发现 Git 仓库，再扫描这些仓库中的上述目录。

使用

临时使用（推荐）

发布到 npm 后，不需要全局安装，直接用 npx 临时下载并执行：

npx --yes agent-skills-scanner
npx --yes agent-skills-scanner --no-open
npx --yes agent-skills-scanner --json --code-root ~/workspace

如果本机默认 npm registry 不是公网源，可以显式指定：

npx --yes --registry=https://registry.npmjs.org/ agent-skills-scanner --no-open

agent-skills-scan 和 scan-agent-skills 也是可用的命令别名：

npx --yes agent-skills-scan --no-open

CLI 入口由 Node.js 启动，但实际扫描器仍使用 Python 标准库，因此运行环境需要：

• Node.js 16 或更高版本
• Python 3（命令行中可用 python3、python 或 Windows 的 py -3）

全局安装

如果经常使用，也可以全局安装：

npm install --global agent-skills-scanner
agent-skills-scanner --no-open

从源码运行

python3 scripts/scan-agent-skills.py

默认生成：

./reports/agent-skills-report.html

生成的 HTML 是自包含单文件，方便直接打开或分享；默认报告路径相对于你执行命令时所在的目录。样式和交互源码集中维护在 scripts/report_template.html。

报告目录已加入 .gitignore，不会被提交。

常用命令：

python3 scripts/scan-agent-skills.py --no-open
python3 scripts/scan-agent-skills.py --json
python3 scripts/scan-agent-skills.py --code-root ~/workspace --output ~/Desktop/agent-skills.html

高级参数保留给特殊场景：--code-root 用于指定代码仓库根目录，--skill-root / --no-default-roots 用于临时扫描指定目录，--output 用于改写 HTML 输出路径。

通过 npm CLI 使用时，后面的参数会原样转发给 Python 扫描器，例如：

npx --yes agent-skills-scanner --code-root ~/workspace --output ~/Desktop/agent-skills.html

发布 npm

维护者发布前先执行打包检查和测试：

npm install
npm test
npm run pack:check

确认 npm 账号和包名后发布：

npm login
npm publish

publishConfig 已固定使用公网 npm registry：https://registry.npmjs.org/。

prepublishOnly 会在真正发布前自动运行 npm test。发布后可以在一个临时目录验证：

mkdir /tmp/agent-skills-scanner-smoke-test
cd /tmp/agent-skills-scanner-smoke-test
npx --yes --registry=https://registry.npmjs.org/ agent-skills-scanner --no-open

当前包元数据仍使用 UNLICENSED。如果要公开分发，请在发布前补充仓库认可的许可证，并同步更新 package.json 和许可证文件。

报告能力

• HTML 报告采用 Explorer / Content / Overview 三栏结构。
• 左侧按 用户级/项目级 -> Agent 端 -> host/project -> skill 导航。
• 中间内容支持分组折叠，搜索命中会自动展开对应路径。
• 右侧为静态总览，不参与筛选。
• 展示 skill name、description、tool、host、scope、绝对路径。
• 搜索支持名称、描述、工具、宿主和路径。
• 搜索结果会自动展开命中的分组并高亮关键词。

开发验证

python3 -m unittest discover -s tests -v
python3 scripts/scan-agent-skills.py --no-open
python3 scripts/scan-agent-skills.py --json