[dirtybits]

What this changes

Phase 1, PR 3 of .agents/plans/skill-evals-and-packages.plan.md. Independent of #274.

Decision I took for you (Q8): you closed my question card and asked me to continue. So this PR follows the plan's proposal: static check results show on the skill page and in /api/check as a display-only signal. It can only warn. It never changes recommended_action or the "Trusted / Review / Avoid" verdict. If you want "API only" or "hidden" instead, tell me and I will change it.

New static checks (web/lib/skillStaticChecks.ts, version static-v1). They read every file of a skill, so they also cover the part of a large tree that the AI scan cuts off. They need no model and cost nothing.

Rule	Severity	Finds
Agent Skills frontmatter	low / info	Missing or invalid name and description, compatibility over 500 characters, fields outside the spec. Rules come from the upstream spec and the skills-ref validator (checked 2026-11-04).
Hidden Unicode	medium	Bidirectional controls, zero-width characters, Unicode tag characters, stacked variation selectors. Normal emoji, real flag emoji, and joiners in scripts such as Persian are allowed.
Download-and-run	medium	curl … | sh, wget … | sudo bash, bash <(curl …), sh -c "$(curl …)", iwr … | iex, and similar. || and curl … | jq are not flagged.
Secrets	medium	Private keys (with key data), AWS, GitHub, Slack, Stripe live, Anthropic, OpenAI, and Google keys, and 64-byte Solana keypair arrays. Documentation placeholders are skipped.
Archives	medium / info	Password-protected zip files (cannot be checked). Other archives get an info note.

• No file content in findings. A finding gives the rule, file, first line, and a count, never an excerpt or a secret value. The URL inventory keeps host names only. So paid skills stay private before purchase.
• Signal: static_checks is pass (nothing above low), warn (any medium finding), or unknown (no checks on record). It never gives fail.
• Storage: additive skill_static_checks table, primary key (tree_hash, checks_version), the same pattern as skill_scans.
• When checks run: after a publish, a new version, and every mirror sync, also when the mirror skips the AI review. /api/check checks uploaded files without storing them, and uses the cache for stored skills.
• Shown in: the trust checklist on the skill page, GET /api/skills/{id} (static_checks), and /api/check (static_checks plus the signal). Browse cards do not change.

After merge: run the backfill once

Existing skills show "Static checks: n/a" until their checks exist. From web/ on the Mac:

npx tsx --env-file=.env.local ./scripts/backfill-skill-static-checks.ts           # dry run, no writes
npx tsx --env-file=.env.local ./scripts/backfill-skill-static-checks.ts --apply   # writes the reports

It prints the database host first. It reads stored trees directly, so it records no download events. Large mirrored trees can fail to read until #274 merges, because #274 fixes the stored-tree read limits.

Verified

• npm run format:check, npm run lint, npm run typecheck, CLI tsc --noEmit.
• npm test: web 165 files, 1,660 tests; CLI 17 files, 137 tests.
• New tests for each rule, with cases that must be found and cases that must not (emoji, Persian text, ||, placeholders). A test confirms that a warn never changes recommended_action.
• Mutation checks: treating || as a pipe, running the archive check before the text checks, keeping a leading byte order mark, and the old flag-emoji rule each make a test fail.
• next build --webpack compiled and ran TypeScript, then stopped at the /sitemap.xml prerender because this workspace has no DATABASE_URL. The Vercel preview is the real build check.

Not verified

• The backfill has not run on production.
• No live request on the preview.

Notes for merging

• feat(cli): check skill downloads against the published tree hash #274 also changes web/public/skill.md to version 2.3.0. That is the same line change, so it merges cleanly.
• Both PRs add a dated note at the end of the plan file. The second one to merge will need a small conflict fix. I will do it when it happens.

---

---

Generated by Claude Code