| name | asset-library-organization-planner |
| description | Plan an internal asset library structure (folders, naming, metadata, license tracking, version control) so future recipes find and reuse assets reliably. |
asset-library-organization-planner
Purpose
Set up a maintainable internal asset library so future recipes can:
- find existing assets quickly,
- avoid re-licensing the same source,
- reuse PBR materials and HDRIs,
- track versions and revisions.
Quick start
- pin folder structure (kebab-case, by category)
- pin naming convention (asset name + version + license slug)
- pin metadata schema (license, source, date, version, hash)
- pin version control rules (LFS for large binaries, plain text for metadata)
- emit a library-init plan
When to use
- starting a new BlendOps repo with multiple recipes
- existing library is disorganized; recipes can't find assets
- before scaling to 50+ assets
When not to use
- single-recipe repo with < 5 assets
- pure planning before any asset is sourced
- as a substitute for license check (use
asset-license-checker)
Trigger phrases
- "organize the assets"
- "asset library structure"
- "where should assets go"
- "name our assets"
Prerequisites / readiness
- baseline asset count + categories known
- version control system known (git + LFS / Perforce / DAM)
- internal team conventions (if any)
Input schema
Required inputs
| Input | Why it is required |
|---|
| Asset categories | Drives folder structure |
| Version control system | Drives binary storage rules |
| Existing convention (if any) | Maintain consistency |
Optional inputs
| Input | Use |
|---|
| Team size | Affects review process |
| Cloud storage / DAM | Alternative storage path |
Assumptions to confirm
- The library is shared across future recipes.
- License metadata must be queryable.
- Versioning is discrete (not "latest" symlinks; pinned versions).
Output schema
Primary output
A library plan: folder tree, naming convention, metadata schema, version control rules, license tracking strategy.
Secondary output
- migration steps if existing assets need re-organizing
- review process for adding new assets
- evidence label
Evidence / caveat output
Runtime status: Not Run | Attempted | Produced | Verified | Failed | Blocked / Not Run
Artifact status: Not Run | Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>
Required laws
../../laws/evidence-before-done.md../../laws/non-blender-user-language.md../../laws/no-arbitrary-python-interface.md../../laws/official-runtime-only.md
Official runtime boundary
Planning skill — does not move files, does not run Blender, does not configure version control. Outputs a structure spec.
Operating procedure
- Read asset categories.
- Pin folder structure (see
references/folder-structure-rules.md).
- Pin naming convention (see
references/naming-rules.md).
- Pin metadata schema (see
references/metadata-schema.md).
- Pin version control rules (LFS thresholds, branching).
- Pin license tracking (one license file per asset folder).
- Recommend a review process for new asset additions.
- Emit library-init plan + migration steps.
Decision tree
< 50 total assets?
→ Simple flat structure may suffice
50-500 assets?
→ Categorical folders + subfolders
500+ assets?
→ DAM (Digital Asset Management) tool recommended
Mostly small files (< 50MB each)?
→ Plain git OK
Mixed sizes including > 50MB?
→ Git LFS or external storage
> 1GB total?
→ External DAM strongly recommended
Playbooks
Playbook A: Small repo (< 50 assets)
Flat folders by category: assets/models/, assets/textures/, assets/hdris/, assets/fonts/. One README + LICENSES.md per folder.
Playbook B: Medium repo (50-500 assets)
Nested by category + sub-category: assets/models/products/, assets/models/characters/, assets/textures/pbr/, etc. Per-asset LICENSE.txt + metadata.json.
Playbook C: Large repo (500+)
External DAM (e.g. Tractor, Razuna, custom) + git pointer files. Library plan focuses on naming + metadata schema; storage is offloaded.
Mode handling
Text-only mode
Library plan only.
Runtime-ready mode
Plan + recommended directory creation steps (operator runs them; this skill does not).
Blocked runtime mode
Plan only.
Validation checklist
Pass / Warn / Fail rubric
| Verdict | Criteria |
|---|
| Pass | All sections pinned + migration plan if needed + review process. |
| Warn | One section soft (e.g. metadata schema partial). |
| Fail | "Just dump in a folder" advice; no naming convention; no license tracking. |
Failure handling
- Existing library cannot be reorganized → plan a parallel new library + gradual migration.
- VCS not in place → recommend git or alternative before any asset commit.
- Team lacks process discipline → recommend lightweight review checklist (1-page).
Troubleshooting
| Problem | Response |
|---|
| Asset duplicates across folders | Add a hash check; deduplicate before re-organizing. |
| Lost license info on old assets | Mark as Quarantine; do not use until re-licensed. |
| Naming inconsistency | Apply convention to new only; rename old in batches with care. |
Best practices
- One library, one source of truth.
- License lives next to the asset, always.
- Naming convention is unforgiving; enforce in code review.
- Avoid deeply-nested folders (> 4 levels gets confusing).
Good examples
- "assets/models/products/sneaker-v01-cc0.glb + assets/models/products/sneaker-v01-cc0.metadata.json + assets/models/products/sneaker-v01-cc0.LICENSE.txt"
Bad examples
- "Just use a Drive folder." — no version, no license tracking.
User-facing response template
Library size estimate: <N assets>
VCS: <git / git+lfs / DAM>
Folder structure:
<tree>
Naming convention: <pattern + examples>
Metadata schema (per asset):
<fields>
Version control:
<rules>
License tracking: <strategy>
Review process: <1-page checklist>
Migration steps (if applicable): <list>
Limitations: <gaps>
Next: implement plan; future recipes use this library
Anti-patterns
- "Just a folder."
- No license file.
- Mutable "latest" pointers.
- Mixing assets and recipes in the same folders.
Cross-skill handoff
- Asset discovery →
../blender-asset-discovery-planner/SKILL.md
- License →
../asset-license-checker/SKILL.md
- Style →
../asset-style-consistency-checker/SKILL.md
- Fallback →
../asset-fallback-strategy/SKILL.md
Non-goals
- Move files.
- Configure git / DAM.
- Run Blender.
- Buy assets.
References
references/folder-structure-rules.mdreferences/naming-rules.mdreferences/metadata-schema.md../../docs/skill-system.md
