{"slug": "show-hn-skillpreflight-score-ai-agent-skills-before-installing-them", "title": "Show HN: SkillPreflight – score AI agent skills before installing them", "summary": "SkillPreflight, a new open-source command-line tool, scores AI agent skills on a 100-point scale across security, permission restraint, token efficiency, lightweight footprint, maintainability, reliability, and compatibility before installation. The tool, run via npx, scans local directories or GitHub repositories for skills used in Codex, Claude Code, Cursor, and Gemini CLI, and supports JSON policy files to exclude files and ignore rules. It aims to help users avoid unsafe or bloated third-party skills by providing pre-install safety checks.", "body_md": "SkillPreflight is a pre-install safety, token, and maintainability scorecard for AI agent skills.\n\nIt helps users decide whether a Codex, Claude Code, Cursor, Gemini CLI, or other agent skill is safe and lightweight enough to install.\n\nIf SkillPreflight helps you vet a third-party skill, consider starring the repository so more users can discover safer pre-install checks.\n\nRun without installing:\n\n```\nnpx skill-preflight scan ./my-skill\n```\n\nScan a GitHub repository before installing it:\n\n```\nnpx skill-preflight scan https://github.com/user/some-skill\n```\n\nScan one skill inside a large repository by pasting its GitHub directory or `SKILL.md`\n\nURL:\n\n```\nnpx skill-preflight scan https://github.com/user/skills/tree/main/skills/my-skill\nnpx skill-preflight scan https://github.com/user/skills/blob/main/skills/my-skill/SKILL.md\n```\n\nScan common local skill directories:\n\n```\nnpx skill-preflight scan --installed\n```\n\nFor repositories containing many skills, show a compact list of the 20 lowest-scoring skills:\n\n```\nnpx skill-preflight scan https://github.com/user/skill-collection --summary --top 20\n```\n\nApply a local policy when scanning a repository:\n\n```\nnpx skill-preflight scan . --config skill-preflight.json\nnpm install\nnpm run build\nnpm test\nnpm run dev -- scan examples/risky-skill\n```\n\nSkillPreflight uses a 100-point score:\n\n| Category | Points | What it checks |\n|---|---|---|\n| Security | 35 | Dangerous commands, secret access, exfiltration, prompt injection, remote script execution |\n| Permission restraint | 15 | Over-broad activation, unnecessary shell/network/file access |\n| Token efficiency | 15 | Oversized `SKILL.md` , repeated content, poor progressive disclosure |\n| Lightweight footprint | 10 | File count, total size, dependencies, large assets |\n| Maintainability | 10 | README, license, frontmatter, examples, documentation hygiene |\n| Reliability | 10 | Tests, fixtures, deterministic workflow, error handling |\n| Compatibility | 5 | Hardcoded local paths, OS-specific assumptions, fragile shell usage |\n\nRepeated locations for the same rule remain visible, but each rule ID deducts points only once per skill. This keeps large repositories from receiving a lower score merely because the same issue appears in several files.\n\nWhen one skill directory contains other skills, SkillPreflight reports each `SKILL.md`\n\nas a separate skill and excludes child-skill files from the parent score.\n\n```\nskill-preflight scan <target>\n```\n\nOptions:\n\n```\n--installed             Scan common installed skill directories.\n--format <format>       text, json, markdown, html, or sarif. Default: text.\n--out <file>            Write report to a file.\n--fail-below <score>    Exit with code 1 if any scanned skill is below this score.\n--fail-on <severity>    Exit for findings at or above info, low, medium, high, or critical.\n--config <file>         Load an explicit JSON policy file.\n--exclude <glob>        Exclude a target-relative path glob. Repeat as needed.\n--ignore-rule <id>      Suppress a rule ID or wildcard pattern. Repeat as needed.\n--keep-temp             Keep temporary clones for debugging.\n--summary               Show aggregate results and the lowest-scoring skills only.\n--top <count>           Number of skills shown with --summary. Default: 20.\n```\n\nSummary mode supports text, JSON, Markdown, and HTML output. SARIF always contains the full set of findings for code scanning.\n\nUse an explicit JSON policy to keep generated files and reviewed false positives out of a scan:\n\n```\n{\n  \"exclude\": [\"fixtures/**\", \"vendor/**\"],\n  \"ignoreRules\": [\"compatibility.os-specific-command\"],\n  \"failBelow\": 70,\n  \"failOn\": \"high\"\n}\nskill-preflight scan . --config skill-preflight.json\n```\n\nConfig files are never loaded from a scanned repository automatically. This prevents an untrusted remote skill from suppressing its own findings. CLI exclusions and ignored rules are merged with the config; CLI score and severity gates take precedence.\n\nSuppressed findings remain counted in the report so policy decisions are visible. See `docs/policy.md`\n\nfor glob behavior and CI examples.\n\nGenerate Shields-compatible badge JSON:\n\n```\nskill-preflight badge ./my-skill --out skill-preflight-badge.json\n```\n\nThe badge payload can be served through a static endpoint or GitHub Pages:\n\n```\n{\n  \"schemaVersion\": 1,\n  \"label\": \"SkillPreflight\",\n  \"message\": \"91/100 A\",\n  \"color\": \"brightgreen\"\n}\n```\n\nAfter the package is published to npm and the repository is tagged, skill authors can scan every PR:\n\n```\nname: SkillPreflight\n\non: [pull_request, push]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - uses: agent-contracts/skill-preflight@v1\n        with:\n          target: \".\"\n          config: skill-preflight.json\n```\n\nWithout a config, the Action fails below 70 by default. A policy file's `failBelow`\n\nvalue is used when `config`\n\nis provided; an explicit `fail-below`\n\ninput overrides both.\n\nFor GitHub code scanning, emit SARIF:\n\n```\nskill-preflight scan . --format sarif --out skill-preflight.sarif\n```\n\nSee `docs/github-action.md`\n\nfor the full workflow.\n\nIn August 2026, SkillPreflight scanned a frozen, commit-pinned sample of 40 public agent skills. The sample averaged **80.8/100**, with a median score of **85.5/100**.\n\nRead the [reproducible benchmark report](/agent-contracts/skill-preflight/blob/main/benchmarks/2026-08-public-skills/README.md) for the methodology, aggregate findings, source snapshot, and raw JSON/CSV data. This convenience sample is not an ecosystem ranking, and static findings require manual review.\n\nSkillPreflight does not execute scripts inside scanned skills. It only reads files and performs static analysis. Oversized files are measured without being loaded into text analysis.\n\n```\nshell-super-agent: 35/100 (F) - High risk, do not install blindly\n\nTop findings:\n- [CRITICAL] Remote script execution pattern (SKILL.md:15)\n- [HIGH] Prompt injection language (SKILL.md:8)\n- [HIGH] Potential secret or credential access (SKILL.md:10)\n```\n\nSee `docs/rules.md`\n\nfor the current static analysis rule catalog, including dependency, install-script, MCP config, token, and compatibility checks.\n\nSee `docs/release.md`\n\nfor the first npm and GitHub release checklist.", "url": "https://wpnews.pro/news/show-hn-skillpreflight-score-ai-agent-skills-before-installing-them", "canonical_source": "https://github.com/agent-contracts/skill-preflight", "published_at": "2026-08-25 10:08:13+00:00", "updated_at": "2026-08-25 10:45:04.635171+00:00", "lang": "en", "topics": ["ai-tools", "ai-safety", "developer-tools"], "entities": ["SkillPreflight", "Codex", "Claude Code", "Cursor", "Gemini CLI"], "alternates": {"html": "https://wpnews.pro/news/show-hn-skillpreflight-score-ai-agent-skills-before-installing-them", "markdown": "https://wpnews.pro/news/show-hn-skillpreflight-score-ai-agent-skills-before-installing-them.md", "text": "https://wpnews.pro/news/show-hn-skillpreflight-score-ai-agent-skills-before-installing-them.txt", "jsonld": "https://wpnews.pro/news/show-hn-skillpreflight-score-ai-agent-skills-before-installing-them.jsonld"}}