Skill Auditor npm Package: The Quick Start Guide

你為什麼需要

AI Agent skill 是新的 npm 套件。開發者發布、社群分享、Agent 安裝。但和 npm 不同,skill 檔沒有內建安全掃描。一個惡意 SKILL.md 就能注入 prompt、外洩 secret、或劫持你的 Agent。

Panguard Skill Auditor 是安全閘門。它對任何 skill 檔跑 8 項檢查,回傳量化風險分數。現在你可以把它當獨立 npm 套件用 — 不用裝 CLI、不用 shell script、不用下載 binary。

安裝

npm install @panguard-ai/panguard-skill-auditor

就這樣。macOS、Linux、Windows 都能跑。沒有 native 依賴。

基本用法

import { auditSkill } from '@panguard-ai/panguard-skill-auditor';

const report = await auditSkill('./skills/some-community-skill');

console.log(report.riskScore);   // 0-100
console.log(report.riskLevel);   // "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
console.log(report.findings);    // 含嚴重度和行號的發現陣列

檢查什麼

Auditor 平行跑 6 個獨立檢查:

1. Manifest 驗證 — 檢查 SKILL.md 結構、必填欄位、metadata 一致性 2. 指令分析 — 偵測 prompt injection、隱藏 Unicode、編碼 payload、tool poisoning pattern 3. Code 安全(SAST)— 掃所有檔案找寫死 secret、危險命令、code 漏洞 4. 依賴分析 — 交叉比對依賴中的已知安全問題 5. 權限範圍 — 驗證請求權限是否與 skill 描述相符 6. AI 驅動審查 — LLM 深度分析 regex 抓不到的微妙操控 pattern

風險分數解讀

安裝前閘門(3 行)

在危險 skill 進到你的 Agent 之前擋下:

const report = await auditSkill(skillPath);
if (report.riskLevel === 'CRITICAL' || report.riskLevel === 'HIGH') {
  throw new Error(`Blocked: ${skillPath} scored ${report.riskScore}/100`);
}

CI/CD 整合

加進你的 GitHub Actions workflow:

- name: Install Skill Auditor
  run: npm install @panguard-ai/panguard-skill-auditor

- name: Audit skills
  run: |
    node -e "
      const { auditSkill } = require('@panguard-ai/panguard-skill-auditor');
      const fs = require('fs');
      (async () => {
        const dirs = fs.readdirSync('skills', { withFileTypes: true })
          .filter(d => d.isDirectory()).map(d => 'skills/' + d.name);
        for (const dir of dirs) {
          const r = await auditSkill(dir);
          console.log(dir + ': ' + r.riskLevel);
          if (r.riskLevel === 'CRITICAL') process.exit(1);
        }
      })();
    "

選用:AI 驅動分析

Layer 1(regex)抓得到大多數威脅。要更深的語意分析,傳你自己的 LLM:

import type { SkillAnalysisLLM } from '@panguard-ai/panguard-skill-auditor';

const myLLM: SkillAnalysisLLM = {
  analyze: async (prompt) => {
    // 呼叫 Claude、GPT 或任何 LLM
    return await callYourLLM(prompt);
  },
};

const report = await auditSkill('./skills/my-skill', { llm: myLLM });

CLI 替代

如果你偏好命令列:

curl -fsSL https://get.panguard.ai | bash
panguard audit skill ./skills/some-skill --json

接下來

npm 套件目前包含 Layer 1(regex)和 Layer 2(AI 語意)檢查。即將推出的功能包括 Layer 3(Threat Cloud)整合,做即時 IoC 比對,以及對 OpenClaw 生態維護者的註冊處範圍掃描。

Skill Auditor 包含在所有 Panguard 方案中,包含免費 Community 版。今天就開始掃。