asset-library-plan

Purpose

Plan a maintainable internal asset library structure (folder tree, naming convention, per-asset metadata schema, license-tracking strategy, version-control rules, migration steps, and review process) so future recipes can:

• find existing assets quickly,
• avoid re-licensing the same source,
• reuse PBR materials and HDRIs,
• track versions and revisions,
• serve as the internal-library source for asset-discovery and asset-fallback-strategy.

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 → use ../asset-discovery/SKILL.md (Delegates out-of-scope requests to asset-discovery)
• pure planning before any asset categories or storage constraints are known → use ../asset-license-checker/SKILL.md (Delegates out-of-scope requests to asset-license-checker)
• sourcing or acquiring external assets → use ../asset-discovery/SKILL.md (use asset-discovery)
• verifying asset licenses → use ../asset-license-checker/SKILL.md (use asset-license-checker)
• checking visual style consistency across assets → use ../asset-style-check/SKILL.md (use asset-style-check)
• planning fallback substitutions when an asset is missing or fails → use ../asset-fallback-strategy/SKILL.md (use asset-fallback-strategy)
• enforcing file size or polygon/asset count performance budgets → use ../mobile-glb-budget/SKILL.md (use mobile-glb-budget)

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, per-asset 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
Artifact status: Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>

Truth-state rules:

• Default Artifact status is Not Produced.
• States are downgrade-only, never upgrade.
• Planning a library never produces library files (Runtime status: Not Run, Artifact status: Not Produced unless verifying pre-existing external evidence).

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 — never moves files, never configures git/LFS/DAM, never runs Blender, and never produces library files. Outputs a structure spec, migration steps, and review process only.

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 (license file lives next to the asset; unlicensed old assets go to Quarantine for asset-license-checker).
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/. Per-asset license file and metadata file live directly next to each asset file, plus one README per category 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 next to the asset.

Playbook C: Large repo (500+)

External DAM tool + git pointer files. Library plan focuses on folder taxonomy, naming convention, and per-asset metadata/license schema; binary storage is offloaded (operator configures DAM/VCS externally).

Mode handling

Text-only mode

Library structure plan, migration steps, and review process only (Runtime status: Not Run, Artifact status: Not Produced).

Runtime-ready mode

Library plan + recommended directory creation and migration steps for the operator to run manually. This skill never creates directories, never moves files, never configures git/LFS/DAM, and never produces library files (Runtime status: Not Run, Artifact status: Not Produced).

Blocked runtime mode

Library plan only (Runtime status: Not Run, Artifact status: Not Produced).

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: <per-asset license file next to asset + Quarantine rule for unlicensed legacy assets>

Review process: <1-page checklist>

Migration steps (if applicable): <list>

Runtime status: Not Run | Attempted | Produced | Verified | Failed
Artifact status: Not Produced | Produced | Verified | Failed
Evidence used: <links, paths, logs, or "none">
Limitations: <known gaps>
Next: operator implements structure; `asset-discovery` and `asset-fallback-strategy` use this library as their internal source

Anti-patterns

• "Just a folder."
• No license file.
• Mutable "latest" pointers.
• Mixing assets and recipes in the same folders.

Cross-skill handoff

• [upstream_reference] External asset sourcing into this library → ../asset-discovery/SKILL.md
• [upstream_reference] License verification (license file next to asset; unlicensed old assets to Quarantine) → ../asset-license-checker/SKILL.md
• [upstream_reference] Visual style consistency checks → ../asset-style-check/SKILL.md
• [fallback] Consuming this library as fastest fallback source → ../asset-fallback-strategy/SKILL.md
• [progression] File size and asset/polygon count pressure → ../mobile-glb-budget/SKILL.md

Non-goals

• Move, rename, or delete files.
• Configure git, Git LFS, Perforce, or DAM tools.
• Run Blender or execute Python.
• Buy or source external assets (use asset-discovery).
• Verify licenses, style consistency, or performance budgets (use asset-license-checker, asset-style-check, mobile-glb-budget).

References

• references/folder-structure-rules.md
• references/naming-rules.md
• references/metadata-schema.md
• ../../docs/skill-system.md