home / skills / besty0728 / unity-skills / asset

asset skill

safe

/unity-skills/skills/asset

This skill helps organize Unity assets efficiently by batch-moving, importing, or deleting multiple files with optimized batch operations.

npx playbooks add skill besty0728/unity-skills --skill asset

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.0 KB

---
name: unity-asset
description: "Import, manage, and organize assets. Use *_batch skills for 2+ assets."
---

# Unity Asset Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ assets.

## Skills Overview

| Single Object | Batch Version | Use Batch When |
|---------------|---------------|----------------|
| `asset_import` | `asset_import_batch` | Importing 2+ files |
| `asset_delete` | `asset_delete_batch` | Deleting 2+ assets |
| `asset_move` | `asset_move_batch` | Moving 2+ assets |

**No batch needed**:
- `asset_duplicate` - Duplicate single asset
- `asset_find` - Search assets (returns list)
- `asset_create_folder` - Create folder
- `asset_refresh` - Refresh AssetDatabase
- `asset_get_info` - Get asset information

---

## Skills

### asset_import / asset_import_batch
Import external files into the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sourcePath` | string | Yes | External file path |
| `destinationPath` | string | Yes | Project destination |

```python
# Single
unity_skills.call_skill("asset_import",
    sourcePath="C:/Downloads/texture.png",
    destinationPath="Assets/Textures/texture.png"
)

# Batch
unity_skills.call_skill("asset_import_batch", items=[
    {"sourcePath": "C:/Downloads/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "C:/Downloads/tex2.png", "destinationPath": "Assets/Textures/tex2.png"}
])
```

### asset_delete / asset_delete_batch
Delete assets from the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path to delete |

```python
# Single
unity_skills.call_skill("asset_delete", assetPath="Assets/Textures/old.png")

# Batch
unity_skills.call_skill("asset_delete_batch", items=[
    {"path": "Assets/Textures/old1.png"},
    {"path": "Assets/Textures/old2.png"}
])
```

### asset_move / asset_move_batch
Move or rename assets.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sourcePath` | string | Yes | Current asset path |
| `destinationPath` | string | Yes | New path/name |

```python
# Single (also works for rename)
unity_skills.call_skill("asset_move",
    sourcePath="Assets/Materials/Red.mat",
    destinationPath="Assets/Materials/Player/RedMetal.mat"
)

# Batch
unity_skills.call_skill("asset_move_batch", items=[
    {"sourcePath": "Assets/Old/mat1.mat", "destinationPath": "Assets/New/mat1.mat"},
    {"sourcePath": "Assets/Old/mat2.mat", "destinationPath": "Assets/New/mat2.mat"}
])
```

### asset_duplicate
Duplicate an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset to duplicate |

### asset_find
Find assets by search filter.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `searchFilter` | string | Yes | - | Search query |
| `searchInFolders` | string | No | "Assets" | Folder to search |
| `limit` | int | No | 100 | Max results |

**Search Filter Syntax**:
| Filter | Example | Description |
|--------|---------|-------------|
| `t:Type` | `t:Texture2D` | By type |
| `l:Label` | `l:Architecture` | By label |
| `name` | `player` | By name |
| Combined | `t:Material player` | Multiple filters |

**Returns**: `{success, count, assets: [path]}`

### asset_create_folder
Create a folder in the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `folderPath` | string | Yes | Full folder path |

### asset_refresh
Refresh the AssetDatabase after external changes.

No parameters.

### asset_get_info
Get information about an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path |

---

## Example: Efficient Asset Organization

```python
import unity_skills

# BAD: 4 API calls
unity_skills.call_skill("asset_move", sourcePath="Assets/tex1.png", destinationPath="Assets/Textures/tex1.png")
unity_skills.call_skill("asset_move", sourcePath="Assets/tex2.png", destinationPath="Assets/Textures/tex2.png")
unity_skills.call_skill("asset_move", sourcePath="Assets/tex3.png", destinationPath="Assets/Textures/tex3.png")
unity_skills.call_skill("asset_move", sourcePath="Assets/tex4.png", destinationPath="Assets/Textures/tex4.png")

# GOOD: 1 API call
unity_skills.call_skill("asset_move_batch", items=[
    {"sourcePath": "Assets/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "Assets/tex2.png", "destinationPath": "Assets/Textures/tex2.png"},
    {"sourcePath": "Assets/tex3.png", "destinationPath": "Assets/Textures/tex3.png"},
    {"sourcePath": "Assets/tex4.png", "destinationPath": "Assets/Textures/tex4.png"}
])
```

## Best Practices

1. Organize assets in logical folders
2. Use consistent naming conventions
3. Refresh after external file changes
4. Use search filters for efficiency
5. Backup before bulk delete operations

Overview

This skill provides a set of Unity asset management actions for importing, moving, deleting, duplicating, searching, and organizing project assets. It includes batch-first variants for import, move, and delete so you can operate efficiently on multiple assets in a single call. The skill set is designed for common Unity workflows like bringing external files into the project, renaming or relocating assets, and keeping the AssetDatabase in sync.

How this skill works

Each action maps to a focused operation: import copies external files into Assets, move renames or relocates files inside the project, delete removes assets, duplicate creates a copy, find performs search queries, create_folder makes folders, refresh syncs the AssetDatabase, and get_info returns metadata for a path. For operations on two or more assets use the *_batch variant to reduce API calls and improve performance. Search uses Unity-style filters (e.g., t:Texture2D, l:Label, name) and returns a list of matching paths.

When to use it

Import single files or use asset_import_batch when adding many external files at once
Move or rename one asset, or use asset_move_batch to relocate multiple assets in one call
Delete a single obsolete asset or use asset_delete_batch to remove many assets safely
Use asset_find to locate assets by type, label, or name before bulk operations
Call asset_refresh after external changes to ensure the AssetDatabase is up to date

Best practices

Prefer *_batch skills for 2+ items to minimize API calls and reduce overhead
Organize assets into logical folders and use consistent, descriptive names
Run asset_refresh after importing or altering files outside Unity
Use asset_find with targeted filters to verify selections before bulk delete or move
Backup or use version control before performing large batch deletes or moves

Example use cases

Bulk import dozens of textures from a download folder into Assets/Textures using asset_import_batch
Reorganize a project by moving hundreds of assets into new feature folders with asset_move_batch
Clean up legacy assets by finding by label or type and removing them with asset_delete_batch
Create a new folder structure programmatically with asset_create_folder, then import assets into it
Query asset metadata with asset_get_info before duplicating or modifying critical files

FAQ

When should I use the batch variants?

Use batch variants whenever you operate on two or more assets to reduce API calls and speed up processing.

How do I search for specific asset types?

Use asset_find with Unity search filters like t:Texture2D for type, l:Label for labels, or plain text for name matches.