Poly Haven Agent Skill

Search, inspect, and safely download free HDRIs, PBR textures, and 3D models from Poly Haven without leaving your coding-agent workflow.

This repository contains both:

• an Agent Skill that teaches compatible agents how to work with Poly Haven; and
• a standalone, dependency-free Node.js command-line tool that humans can use directly.

This is a community project and is not an official Poly Haven product.

What can it do?

• Search Poly Haven's HDRIs, textures, and models
• Filter by type, category, collection, vault, and structured properties
• Show asset names, descriptions, tags, authors, dimensions, and popularity
• List every available resolution and file format
• Select individual texture maps or complete model packages
• Include package dependencies, such as textures required by a Blend or glTF file
• Show the full download size before transferring anything
• Stream large files safely through temporary .part files
• Verify downloaded files against Poly Haven's published MD5 checksums
• Produce readable tables or JSON for scripts and automation

No Poly Haven API key is required.

Safety first

Downloads are deliberately conservative:

1. You must select a resolution, format, map, package, or exact logical file path.
2. The first download command is a dry run by default.
3. Files are transferred only when --yes is present.
4. Existing files are not replaced unless --force is present.
5. Completed downloads are checksum-verified when Poly Haven supplies an MD5 value.

This matters because one asset can contain many variants and several gigabytes of data.

Requirements

• Node.js 18 or newer
• Internet access to Poly Haven's API and download servers
• Pi or another Agent Skills-compatible harness if you want automatic agent activation

The CLI uses only built-in Node.js modules. There is no npm install step.

Install as a Pi skill

Windows PowerShell

git clone https://github.com/MaksPyn/polyhaven-skill.git "$HOME\.pi\agent\skills\polyhaven"

macOS or Linux

git clone https://github.com/MaksPyn/polyhaven-skill.git ~/.pi/agent/skills/polyhaven

Restart Pi so it discovers SKILL.md. You can then invoke the skill explicitly:

/skill:polyhaven

Pi can also activate it automatically when you ask for Poly Haven assets, HDRIs, materials, or models.

Use the CLI directly

From the repository directory:

node scripts/polyhaven.js --help

1. Search for an asset

node scripts/polyhaven.js search "weathered concrete" --type textures --limit 5

The output includes each asset's ID. Keep that ID for the next commands.

2. Inspect one asset

node scripts/polyhaven.js info concrete_floor_01

3. See the available files

node scripts/polyhaven.js files concrete_floor_01 --flat --resolution 2k

The PATH column is a logical selector such as Diffuse/2k/jpg or blend/2k/blend.

4. Plan a download

node scripts/polyhaven.js download concrete_floor_01 \
  --map Diffuse \
  --resolution 2k \
  --format jpg

Nothing is downloaded yet. Review the destination, file list, and total size.

5. Download after reviewing the plan

node scripts/polyhaven.js download concrete_floor_01 \
  --map Diffuse \
  --resolution 2k \
  --format jpg \
  --output ./assets/concrete_floor_01 \
  --yes

Common examples

Download a 4K HDRI

node scripts/polyhaven.js files sunset_jhbcentral --flat --resolution 4k
node scripts/polyhaven.js download sunset_jhbcentral --select hdri/4k/hdr
node scripts/polyhaven.js download sunset_jhbcentral --select hdri/4k/hdr --yes

Download a Blender model and its textures

node scripts/polyhaven.js files ceramic_vase_03 --flat --package blend
node scripts/polyhaven.js download ceramic_vase_03 \
  --package blend \
  --resolution 2k \
  --include-dependencies

After checking the dry-run plan:

node scripts/polyhaven.js download ceramic_vase_03 \
  --package blend \
  --resolution 2k \
  --include-dependencies \
  --output ./assets/ceramic_vase_03 \
  --yes

Browse categories and properties

node scripts/polyhaven.js taxonomy textures --flat
node scripts/polyhaven.js list --type hdris \
  --attribute environment=outdoor \
  --attribute weather=clear \
  --sort popular

Get JSON instead of a table

node scripts/polyhaven.js search "wood floor" --type textures --limit 20 --json

Main commands

Command	What it does
types	Lists HDRIs, textures, and models
search <words>	Searches asset metadata
list	Lists assets with optional filters
info <id>	Shows one asset's metadata
files <id> --flat	Lists downloadable file variants
taxonomy [type]	Shows categories and structured properties
collections	Lists Poly Haven collections
vaults	Lists Poly Haven vaults
similar <id>	Finds similar assets using a best-effort endpoint
download <id>	Plans or performs a selected download
cache clear	Removes locally cached API responses

Run node scripts/polyhaven.js --help for every option.

Choosing a sensible resolution

• 1K: previews, tests, and distant assets
• 2K: games and ordinary scenes
• 4K: general production and closer views
• 8K or higher: hero assets and special cases where the extra detail is genuinely visible

For Blender/OpenGL workflows, nor_gl is usually the expected normal map. DirectX-oriented workflows commonly use nor_dx.

Configuration

The CLI automatically identifies itself as:

Pi-PolyHaven-Skill/1.0

A product using the live API should set its own recognizable User-Agent:

POLYHAVEN_USER_AGENT=MyAssetBrowser/1.0

Optional environment variables:

Variable	Purpose
POLYHAVEN_USER_AGENT	Identifies your application
POLYHAVEN_BASE_URL	Overrides the API base URL, mainly for testing
POLYHAVEN_CACHE_DIR	Changes the local cache location

Licensing and attribution

Poly Haven assets are published under CC0, so downloaded assets do not require attribution.

Using Poly Haven's live hosted API has separate conditions. Current API terms permit personal, academic, and commercial use, but a live integration must:

• send a recognizable application User-Agent; and
• visibly identify Poly Haven as the source, for example with “Powered by Poly Haven.”

Read the current API terms before shipping an integration. The detailed distinction is also explained in references/terms-and-attribution.md.

Troubleshooting

“Unknown category” or invalid property value

Inspect the live taxonomy and use one of its paths or allowed values:

node scripts/polyhaven.js taxonomy textures --flat

A file already exists

The CLI will skip it if its MD5 already matches. Otherwise, choose another output directory or use --force only when replacement is intentional.

Metadata appears stale

node scripts/polyhaven.js cache clear
node scripts/polyhaven.js search "your query" --no-cache

MD5 verification fails

The incomplete .part file is removed automatically. Retry the download rather than using the failed file.

Repository layout

polyhaven-skill/
├── SKILL.md                       Agent instructions and workflow
├── scripts/polyhaven.js           Standalone CLI
├── references/
│   ├── api-reference.md           Endpoint and metadata reference
│   ├── examples.md                More complete workflows
│   ├── file-layouts.md            HDRI, texture, and model file trees
│   └── terms-and-attribution.md   CC0 and hosted-API conditions
└── tests/polyhaven.test.js        Mocked unit/integration tests

Test the project

node --test tests/polyhaven.test.js

The tests use local mock servers and small fixtures. They do not download production assets.

More documentation

• SKILL.md — complete agent workflow and safety rules
• references/api-reference.md — API endpoints and fields
• references/file-layouts.md — selecting formats, maps, and dependencies
• references/examples.md — additional examples
• references/terms-and-attribution.md — terms and attribution