When to invoke
Use this skill when you need to understand what permissions a skill requires
before granting trust. Invoke it when:
- - Reviewing a new skill before install — a skill has been downloaded or
proposed and you need to know what it accesses before allowing execution.
- - Checking skill permissions — you want a summary of every
permission-relevant signal (binaries, network, env vars, file paths, shell
commands, config files, package managers, risky capabilities).
- - Generating a permission manifest — you need a human-readable markdown
report and a machine-parseable JSON manifest for audit or policy decisions.
- - Deciding whether to sandbox or reject a skill — the skill's observed
behaviour may exceed its declared capabilities and you need a scored
recommendation.
- - Auditing a skill's declared vs observed behaviour — you want to compare
what SKILL.md claims against what the source code actually does.
If the task does not involve evaluating skill trust, permissions, or install
safety, this skill is not the right tool.
How to call — CLI
Run the skill from the command line, passing the skill directory as the
sole argument:
CODEBLOCK0
Stdout: The markdown permission manifest (human-readable report).
Pipe or redirect as needed.
Stderr: Diagnostic warnings from analysis stages, plus the path to the
written JSON file.
Side effect: Writes permission-manifest.json into the skill directory.
This file contains the structured manifest for machine consumption.
Exit code: 0 on success, 1 on invalid arguments or analysis failure.
How to call — programmatic
Import analyzeSkill and call it with the skill directory path:
CODEBLOCK1
The returned AnalysisResult has three fields:
| Field | Type | Description |
|---|
| INLINECODE3 | INLINECODE4 | Complete markdown permission report. |
| INLINECODE5 |
object | Structured manifest matching the markdown data.|
|
diagnostics |
DiagnosticWarning[]| Warnings from discovery, extraction, or classification stages. Each entry has
file,
stage,
message, and
error fields.|
What to do with the output
The analysis produces a disposition recommendation based on how well the
skill's declared metadata matches its observed source-code behaviour. Act on
the recommendation as follows:
- - allow — Declared capabilities match observed behaviour. No undeclared
access detected. Install the skill normally.
- - review — Minor mismatches found (e.g. an undeclared env var or a
low-severity capability gap). Inspect the mismatches in the manifest before
proceeding. A human or policy check should confirm intent.
- - sandbox — Significant undeclared capabilities detected. Install only
within an isolated execution environment with restricted filesystem, network,
and process access.
- - reject — Severe mismatches or dangerous undeclared capabilities.
Do not install. Flag the skill for further investigation or removal from
the registry.
The markdown manifest is the artifact for humans — include it in review
threads, audit logs, or approval workflows. The JSON manifest is for
automated pipelines — feed it to policy engines, dashboards, or gating checks.
If diagnostics is non-empty, some files could not be fully analysed.
Treat a skill with analysis warnings more cautiously — incomplete analysis
means the true permission surface may be larger than reported.
Limitations
- - Static analysis only. The skill inspects source code and metadata files.
It does not execute the skill or trace runtime behaviour. Dynamically
constructed commands, lazy imports, or runtime code generation will not be
detected.
- - No transitive dependency scanning. Only files within the skill directory
are analysed. If the skill depends on external packages that perform
privileged operations, those will not appear in the manifest.
- - Heuristic extraction. Binary, domain, env-var, and shell-command
extraction uses pattern matching. Unusual code patterns may produce false
positives or false negatives.
- - Single-directory scope. The tool analyses one skill directory per
invocation. Multi-skill repositories require separate runs.
何时调用
在授予信任前需要了解技能所需权限时使用此技能。请在以下场景调用：
- - 安装前审查新技能 — 技能已下载或提交，需要在允许执行前了解其访问权限。
- 检查技能权限 — 需要获取所有权限相关信号（二进制文件、网络、环境变量、文件路径、Shell命令、配置文件、包管理器、高风险能力）的摘要。
- 生成权限清单 — 需要生成人类可读的Markdown报告和机器可解析的JSON清单，用于审计或策略决策。
- 决定是否沙箱化或拒绝技能 — 技能的实际行为可能超出其声明能力，需要获取评分建议。
- 审计技能的声明行为与实际行为 — 需要对比SKILL.md声明内容与源代码实际执行内容。
如果任务不涉及评估技能信任度、权限或安装安全性，则此技能不适用。
调用方式 — CLI
通过命令行运行技能，将技能目录作为唯一参数传入：
npx permission-manifest-guard /path/to/skill
标准输出： Markdown格式的权限清单（人类可读报告）。可根据需要管道输出或重定向。
标准错误： 分析阶段的诊断警告，以及写入的JSON文件路径。
副作用： 在技能目录中写入permission-manifest.json文件。该文件包含供机器使用的结构化清单。
退出码： 成功返回0，参数无效或分析失败返回1。
调用方式 — 编程接口
导入analyzeSkill并传入技能目录路径：
typescript
import { analyzeSkill } from permission-manifest-guard;
const result = await analyzeSkill(/path/to/skill);
返回的AnalysisResult包含三个字段：
| 字段 | 类型 | 描述 |
|---|
| markdownManifest | string | 完整的Markdown权限报告。 |
| jsonManifest |
object | 与Markdown数据匹配的结构化清单。|
| diagnostics | DiagnosticWarning[]| 来自发现、提取或分类阶段的警告。每个条目包含file、stage、message和error字段。|
输出处理方式
分析结果会根据技能声明元数据与实际源代码行为的匹配程度生成处置建议。请按以下方式处理：
- - 允许 — 声明能力与实际行为匹配。未检测到未声明的访问。正常安装技能。
- 审查 — 发现轻微不匹配（例如未声明的环境变量或低严重性能力差距）。在继续前检查清单中的不匹配项。需人工或策略检查确认意图。
- 沙箱化 — 检测到重大未声明能力。仅在受限文件系统、网络和进程访问的隔离执行环境中安装。
- 拒绝 — 严重不匹配或危险未声明能力。禁止安装。标记技能以进一步调查或从注册表中移除。
Markdown清单是供人类使用的产物——可纳入审查线程、审计日志或审批流程。JSON清单用于自动化管道——可输入策略引擎、仪表盘或门控检查。
如果diagnostics非空，则部分文件未能完全分析。对存在分析警告的技能应更加谨慎——不完整的分析意味着实际权限面可能大于报告内容。
局限性
- - 仅限静态分析。 技能检查源代码和元数据文件。不执行技能或追踪运行时行为。动态构建的命令、延迟导入或运行时代码生成将无法检测。
- 无传递依赖扫描。 仅分析技能目录内的文件。如果技能依赖执行特权操作的外部包，这些操作不会出现在清单中。
- 启发式提取。 二进制文件、域名、环境变量和Shell命令提取使用模式匹配。异常代码模式可能产生误报或漏报。
- 单目录范围。 每次调用分析一个技能目录。多技能仓库需要单独运行。
