1arley/skill-preflight

Skill Preflight

Audit the supplied skill folder before publication. The audit script treats that folder as untrusted data: it never executes its files, calls a model, or makes network requests. This matters because skills can contain instructions or code that act with an agent's permissions.

1. Get the auditor and run it. It is one self-contained file with no runtime dependencies, published at https://github.com/1arley/skill-preflight:

   curl -fsSL https://raw.githubusercontent.com/1arley/skill-preflight/main/scripts/preflight.mjs -o /tmp/skill-preflight.mjs
   node /tmp/skill-preflight.mjs <skill-folder> --format json
   

   npx --yes github:1arley/skill-preflight <skill-folder> --format json does the same thing and caches the CLI. Download it once and reuse it. Everything after the download runs offline: the auditor never calls a model, never executes the audited skill, and never sends anything anywhere.

   When the folder under review is this skill itself, pass --ignore-file preflightignore.json from the skill folder. It suppresses the two false positives caused by the download URL in this file and in README.md.

2. Read the JSON report and explain each error, warning, and informational portability note in plain language.

3. Apply the qualitative rubric in references/rubric.md to activation clarity, examples, and likely under-activation. Label that judgment separately from deterministic findings.

4. Present one combined report. Keep every deterministic rule ID and file:line location, then append the rubric assessment and its evidence.

5. Suggest focused corrections. Do not edit the audited skill unless the user explicitly asks you to make those corrections.

The agensi profile is heuristic and inspired by Agensi's public security categories. It does not reproduce their private scanner or predict a marketplace decision. Read references/security.md before interpreting security findings and references/report-format.md when converting report formats.

Example

Input:

node /tmp/skill-preflight.mjs ./my-skill --profile default --format json

Deterministic output excerpt:

{
  "schemaVersion": "1.0.0",
  "summary": { "errors": 0, "warnings": 1, "infos": 0 },
  "findings": [{
    "id": "SEC-001", "severity": "warning", "category": "security",
    "message": "Outbound network access is statically referenced.",
    "location": { "file": "scripts/run.mjs", "line": 12 },
    "suggestion": "remove it or document a narrow, user-approved purpose"
  }]
}

The host agent adds a separate qualitative section, for example: “Activation: clear; the description names the task and includes user phrasing. Evidence: the description contains distinct audit and publication triggers.” The script never supplies that judgment.