Asset Library Organization Planner

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

Optional inputs

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

1. Read asset categories.
2. Pin folder structure (see references/folder-structure-rules.md).
3. Pin naming convention (see references/naming-rules.md).
4. Pin metadata schema (see references/metadata-schema.md).
5. Pin version control rules (LFS thresholds, branching).
6. Pin license tracking (one license file per asset folder).
7. Recommend a review process for new asset additions.
8. 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

• Folder structure pinned
• Naming convention pinned
• Metadata schema pinned
• Version control rules pinned
• License tracking strategy pinned
• Review process for new assets
• Migration steps (if existing library)

Pass / Warn / Fail rubric

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

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.md
• references/naming-rules.md
• references/metadata-schema.md
• ../../docs/skill-system.md