| name | compat-hunter |
| description | Use when hunting for OBJ/GLB/glTF/VOX parser compatibility issues by streaming candidate models, parsing each immediately, deleting clean files, and retaining only actionable failures, unknown warnings, or unexplained zero-polygon outputs. Especially useful in the polycss repo with scripts/compat-hunter.mjs. |
Compat Hunter
Use this skill when the user wants to keep digging for parser compatibility issues without building a fixed local corpus.
Workflow
-
In the repo, prefer the reusable script:
pnpm compat-hunter -- --max-models 2000
Equivalent explicit form:
pnpm --filter @layoutit/polycss-core build
node .agents/skills/compat-hunter/scripts/compat-hunter.mjs --max-models 2000
-
Let the script stream remote OBJ/GLB/glTF/VOX candidates, parse each model, and discard clean files. Reports are written under bench/results/, which is ignored by git.
-
Treat these as known non-actionable unless the user asks to support them:
- glTF POINTS/LINES/LINE_LOOP/LINE_STRIP primitives.
- Required Draco or meshopt compressed primitives skipped with a warning.
-
Stop and inspect anything classified as:
throw
unknown-warning
obj-zero-no-warning
glb-zero-no-warning
-
If an actionable parser issue is found, keep the saved file under the report's interesting/ directory, add a focused parser test using that behavior, implement the smallest fix, and rerun the focused parser tests plus the hunter on the saved file or source class.
Useful Commands
Fresh Objaverse and expanded GitHub stream:
pnpm compat-hunter -- --max-models 5000 --max-bytes 10mb --timeout-ms 30000
Objaverse only, later shards:
pnpm compat-hunter -- --sources objaverse --objaverse-shards 120:220 --max-models 5000
GitHub only:
pnpm compat-hunter -- --sources github --max-models 500
Poly Haven only:
pnpm compat-hunter -- --sources polyhaven --polyhaven-limit 250 --max-models 200
VOX-heavy GitHub sources:
pnpm compat-hunter -- --sources github --github-repos ephtracy/voxel-model@master:vox/,mikelovesrobots/mmmm@master:vox/ --max-models 1000
Local directory:
pnpm compat-hunter -- --sources local --local-root /tmp/models --max-models 1000
Keep known-warning files too:
pnpm compat-hunter -- --keep-known --max-models 500
Continue after interesting cases:
pnpm compat-hunter -- --no-stop-on-interesting --max-models 2000
Reporting
Summarize the final report.json with:
pnpm compat-hunter -- --report bench/results/<run>/report.json
In the final response, state the attempted/parsed counts, whether any interesting files were retained, and whether the findings are actionable. Do not imply a clean stream proves full compatibility; it only means this pass found no new actionable parser issue.