From 7e41ad4016c4d8c2609f3143d1a362a0fa856b07 Mon Sep 17 00:00:00 2001 From: Ziyi Zhang Date: Tue, 11 Aug 2026 14:19:41 -0400 Subject: [PATCH] feat: add the generate-editor-search-query skill --- skills/generate-editor-search-query/SKILL.md | 117 +++++++++++++++++ .../references/open-search-window.md | 54 ++++++++ .../references/query-patterns.md | 124 ++++++++++++++++++ 3 files changed, 295 insertions(+) create mode 100644 skills/generate-editor-search-query/SKILL.md create mode 100644 skills/generate-editor-search-query/references/open-search-window.md create mode 100644 skills/generate-editor-search-query/references/query-patterns.md diff --git a/skills/generate-editor-search-query/SKILL.md b/skills/generate-editor-search-query/SKILL.md new file mode 100644 index 0000000..f3b34c6 --- /dev/null +++ b/skills/generate-editor-search-query/SKILL.md @@ -0,0 +1,117 @@ +--- +name: generate-editor-search-query +description: Generates Unity Search / Quick Search queries and opens the Unity Search window for read-only Unity Editor asset or scene-object lookup requests. Always use when the user asks to find, search, show, locate, filter, look up, query, or list concrete assets or scene objects in the current project or scene, even if Unity Search is not named. Covers materials, textures, prefabs, scenes, scripts, shaders, GameObjects, components, Lights, Cameras, UI objects, labels, paths, references, selected or named assets, and asset types. Also use when the user explicitly mentions Unity Search, Quick Search, Search window, open Search, or asks what Unity Search query to use. Do not use for general project overview, project structure, folder-purpose summaries, gameplay/system explanations, how-to programming questions, web search, repository text search, build logs, package installation, menu or settings search, modifying results, or non-Unity filesystem search unless the user explicitly asks to use Unity Search. +enabled: true +modes: [agent, ask] +--- + +Translate natural-language Unity Editor search requests into useful Unity Search queries, explain them briefly, and open the Unity Search window with the query when appropriate. + +## Default Behavior + +If the prompt explicitly says Unity Search, Quick Search, Search window, open Search, or asks for a Unity Search query, handle the search request with this skill even when the target belongs to another domain such as lighting, UI, physics, audio, or animation. + +For requests such as "find", "search", "locate", "list", "filter", "look up", "where is", "which assets use", or "what references" concrete Unity assets or scene objects: + +1. Determine whether the request is primarily about project assets, scene objects, or both. +2. Build one concise Unity Search query. +3. Show the query in the response before or while opening Search. +4. Open Unity Search by running the Editor-side snippet unless the user explicitly asks for query text only. +5. If opening Search fails, return the query and tell the user to paste it into Unity Search manually. + +Do not open Search when the user says "do not open Search", "query only", "what query should I use", "just give me the query", or similar. + +If the user asks for a general explanation, project overview, folder-structure summary, architecture walkthrough, gameplay-system summary, or "how do I" programming answer, do not use this skill unless the prompt explicitly asks for Unity Search, a Search query, or opening the Search window. + +If the user refers to "this", "selected", or "current" without an attached asset, scene object, visible name, or path, ask for the name/path instead of inventing one. + +## Scope + +Scope read-only Unity Search / Quick Search queries to: + +- project assets such as materials, textures, prefabs, scenes, scripts, shaders, audio clips, sprites, meshes, models, animations, fonts, render textures, and ScriptableObject assets +- scene objects and components such as Cameras, Lights, Rigidbodies, Colliders, Renderers, Canvas objects, UI components, ParticleSystems, AudioSources, Animators, Terrain objects, and named GameObjects +- path, label, type, filename, keyword, and reference-oriented asset searches +- selected or named assets when the name/path is available from the conversation or attachment + +Do not install packages, run menu commands, edit assets, modify scenes, search external documentation, search repository text, inspect build logs, delete results, fix search results, or perform dependency graph analysis. If the user asks to act on results, first open Search or provide the query, then ask for confirmation before any separate modifying skill or workflow. + +## References + +Before generating non-trivial queries, read [references/query-patterns.md](references/query-patterns.md). + +Before opening the Search window, read [references/open-search-window.md](references/open-search-window.md). + +Official English references: + +- [Unity Search](https://docs.unity3d.com/Manual/search-overview.html) +- [Search expressions](https://docs.unity3d.com/Manual/search-expressions.html) +- [SearchService.ShowWindow](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Search.SearchService.ShowWindow.html) + +## Passing C# to `eval` + +`eval` compiles a **statement block, not a file**. Two consequences, both compile errors: + +- **No `using` directives.** The compiler reads `using UnityEditor;` as a resource-disposal + statement and rejects it (`CS0210`). +- **Types must be fully qualified.** A bare `SearchService` does not resolve (`CS0246`), and a + bare `Object` is ambiguous with `object` (`CS0104`). + +The `unity-cli` skill owns the prerequisites — installing the CLI, confirming a connected Editor, +adding the project's `com.unity.pipeline` package, and discovering the command catalog. You need +`eval` in particular; if it is absent, generate the query text and say the window can't be opened. + +## Query Generation Rules + +Use the simplest query that is likely to produce the requested result. + +- Prefer type filters for asset and component requests, such as `t:material`, `t:texture`, `t:prefab`, `t:scene`, `t:script`, `t:shader`, `t:Light`, or `t:Rigidbody`. +- Preserve user-provided names and keywords as plain query terms unless they need quoting. +- Use `dir:` when the user gives a folder or says "in Assets/..." or "under ...". +- Use `l:` when the user asks for a Unity asset label. +- Use `ref=` when the user asks what references, uses, depends on, contains, or is connected to an asset. +- Use Search expressions only when they clearly improve the query, such as `t:prefab ref={t:texture}` or `t:scene ref={t:prefab}`. +- For selected/current wording, use the known selected asset name or path only if it is present in the chat context; otherwise ask for it. +- For broad relationship requests such as "where is Rigidbody used", use a simple keyword or component query first, then mention that a scripted audit is separate if the user needs exhaustive code/property analysis. +- For requests that mix Search with repair work, generate and open the query first; do not modify results unless the user explicitly confirms a separate follow-up action. +- Do not invent unsupported filters for uncertain requests. If a request cannot be expressed reliably with Unity Search syntax, open the closest safe query and state the limitation. + +## Opening Unity Search + +Run C# in the Editor only to open the Search window. This is an Editor UI action and must not change project assets or scene contents. + +When opening Search: + +1. Escape the query safely in the generated C# string. +2. Prefer asset and scene providers for this v1 skill. +3. Fall back to active providers if a provider is unavailable. +4. Log the query that was opened. +5. Never claim Search opened if the command failed. + +## Response Format + +Keep the user-facing response short: + +```text +Query: `t:material` +Opened Unity Search with that query. +``` + +If not opening Search: + +```text +Query: `t:prefab ref={t:texture}` +Paste this into Unity Search. +``` + +If the request is ambiguous but still searchable, choose the most likely query and mention the assumption. Ask a question only when the search target cannot be inferred, such as "find the thing" with no asset, scene, type, name, or context. + +## Validation Checklist + +Before reporting success: + +- the generated query is shown to the user +- the query targets assets, scene objects, or both +- Search was opened only when the user did not opt out +- any fallback or uncertainty is stated plainly +- no asset, scene, package, project setting, or search result was modified diff --git a/skills/generate-editor-search-query/references/open-search-window.md b/skills/generate-editor-search-query/references/open-search-window.md new file mode 100644 index 0000000..ba82d60 --- /dev/null +++ b/skills/generate-editor-search-query/references/open-search-window.md @@ -0,0 +1,54 @@ +# Open Unity Search Window + +Use this pattern when the skill should open Unity Search pre-populated with a generated query. + +This is a read-only Editor UI action. It must not create, modify, delete, import, install, or save anything. + +## Editor-side snippet + +Replace `QUERY_HERE` with the generated Unity Search query. If the query contains double quotes, double them inside the verbatim C# string. + +Run it through the Editor with `unity command eval --code ''`. Fully qualified, with no +`using` directives, because `eval` compiles a statement block rather than a file. + +```csharp +const string query = @"QUERY_HERE"; + +var candidates = new[] +{ + UnityEditor.Search.SearchService.GetProvider("asset"), + UnityEditor.Search.SearchService.GetProvider("scene") +}; +var preferredProviders = System.Linq.Enumerable.ToArray( + System.Linq.Enumerable.Where(candidates, provider => provider != null)); + +var context = preferredProviders.Length > 0 + ? new UnityEditor.Search.SearchContext(preferredProviders, query) + : new UnityEditor.Search.SearchContext(UnityEditor.Search.SearchService.GetActiveProviders(), query); + +UnityEditor.Search.SearchService.ShowWindow(context); +return $"Opened Unity Search with query: {query}"; +``` + +## Fallback Behavior + +If compilation or execution fails: + +1. Do not claim Search opened. +2. Show the query to the user. +3. Tell the user to paste it into Unity Search manually. +4. If the error indicates `UnityEditor.Search` is unavailable, say the project/editor version may not expose the Modern Search API used by the opener. + +## Provider Choice + +For v1, prefer the `asset` and `scene` providers because this skill is scoped to project assets and scene objects. + +Use active providers only as a fallback when one or both preferred providers are unavailable. + +## Safety Rules + +- Do not call APIs that act on search results. +- Do not select, ping, rename, delete, move, import, or edit results. +- Do not save assets or scenes. +- Do not create project scripts or editor windows. +- Do not run package, menu, settings, or dependency searches as v1 behavior. diff --git a/skills/generate-editor-search-query/references/query-patterns.md b/skills/generate-editor-search-query/references/query-patterns.md new file mode 100644 index 0000000..26315f1 --- /dev/null +++ b/skills/generate-editor-search-query/references/query-patterns.md @@ -0,0 +1,124 @@ +# Unity Search Query Patterns + +Use these patterns to translate common natural-language requests into Unity Search queries. Keep queries simple unless the user asks for a more complex relationship. + +## Table of Contents + +- [Asset Queries](#asset-queries) +- [Reference Queries](#reference-queries) +- [Scene Queries](#scene-queries) +- [Natural-Language Mapping](#natural-language-mapping) +- [Mixed Asset And Scene Queries](#mixed-asset-and-scene-queries) +- [Unsupported Or Risky Requests](#unsupported-or-risky-requests) +- [Query Quality Rules](#query-quality-rules) + +## Asset Queries + +| User intent | Query | +| --- | --- | +| Find all materials | `t:material` | +| Find all textures | `t:texture` | +| Find materials and textures | `t:[material, texture]` | +| Find prefabs | `t:prefab` | +| Find scenes | `t:scene` | +| Find scripts | `t:script` | +| Find shaders | `t:shader` | +| Find sprites | `t:sprite` | +| Find audio clips | `t:audioclip` | +| Find animation clips | `t:animationclip` | +| Find meshes/models | `t:mesh` | +| Find fonts | `t:font` | +| Find render textures | `t:rendertexture` | +| Find ScriptableObject assets | `t:ScriptableObject` | +| Find assets in a folder | `dir:Assets/FolderName` | +| Find prefabs in a folder | `t:prefab dir:Assets/FolderName` | +| Find materials in a folder | `t:material dir:Assets/FolderName` | +| Find assets by label | `l:LabelName` | +| Find assets by name or keyword | `keyword` | + +If the user gives an asset extension or filename pattern, include it as a keyword or glob-style term when useful, such as `*.prefab`, `*.mat`, or `Player`. + +## Reference Queries + +Use `ref=` when the request is about usage, references, dependencies, or "what uses this". + +| User intent | Query | +| --- | --- | +| Find prefabs that reference textures | `t:prefab ref={t:texture}` | +| Find scenes that reference prefabs | `t:scene ref={t:prefab}` | +| Find assets that reference a named asset | `ref=AssetName` | +| Find scenes referencing a specific prefab path | `t:scene ref="Assets/Path/Prefab.prefab"` | +| Find prefabs that use a material | `t:prefab ref=MaterialName` | +| Find materials that use a texture | `t:material ref=TextureName` | +| Find scenes that use a script or component name | `t:scene ScriptOrComponentName` | +| Find prefabs that mention a script or component name | `t:prefab ScriptOrComponentName` | + +If the user gives a specific selected asset but the exact path is unknown, use the visible asset name first and say that a path-specific query will be more precise. + +## Scene Queries + +Scene-object searches should use component type names or object-name keywords. These queries are intended for the scene provider. + +| User intent | Query | +| --- | --- | +| Find Lights | `t:Light` | +| Find Cameras | `t:Camera` | +| Find Rigidbodies | `t:Rigidbody` | +| Find Colliders | `t:Collider` | +| Find Canvas UI objects | `t:Canvas` | +| Find UI Buttons | `t:Button` | +| Find TextMeshPro UI text | `t:TextMeshProUGUI` | +| Find RectTransforms | `t:RectTransform` | +| Find Particle Systems | `t:ParticleSystem` | +| Find AudioSources | `t:AudioSource` | +| Find Animators | `t:Animator` | +| Find MeshRenderers | `t:MeshRenderer` | +| Find SkinnedMeshRenderers | `t:SkinnedMeshRenderer` | +| Find NavMeshAgents | `t:NavMeshAgent` | +| Find Terrain objects | `t:Terrain` | +| Find objects by name | `ObjectName` | + +For scene object requests that mention both a name and a component, combine them, for example `Enemy t:Rigidbody`. + +## Natural-Language Mapping + +Map common phrases to stable query forms: + +| User wording | Query strategy | +| --- | --- | +| "where is X" | Use `X` as a keyword query unless X is clearly a type. | +| "which prefabs use X" | Use `t:prefab ref=X` when X is an asset name; otherwise use `t:prefab X`. | +| "what references this texture" | Use `ref=TextureName`, or `ref="Assets/Path/Texture.png"` if a path is available. | +| "what references the selected material" | Use the selected asset name/path if provided; otherwise ask for the material name or path. | +| "show all X in Assets/UI" | Use `t:x dir:Assets/UI` when X maps to an asset type. | +| "find scene objects with X" | Use `t:X` when X is a component type; otherwise use `X`. | +| "find current scene objects named X" | Use `X` with scene providers; add a component type only when the user specifies one. | +| "query only" | Return the query and do not open Search. | + +## Mixed Asset And Scene Queries + +If the user asks broadly, such as "find everything related to Rigidbody", open Search with active asset and scene providers and use the plain keyword plus likely type: + +- `Rigidbody` +- `t:Rigidbody` +- `Player Rigidbody` + +For "materials using Standard shader" or other property-specific material questions, Unity Search may not expose every material shader property consistently across versions. Prefer a query such as `t:material Standard` and state that it narrows to likely matches; a scripted audit is a separate task. + +## Unsupported Or Risky Requests + +Do not pretend Unity Search can reliably express every inspection. + +- Missing script detection might need a scripted scan. Use a broad query such as `missing script` or `t:prefab missing` only as a starting point and state the limitation. +- Deep dependency graph questions are not this skill's scope. Provide a Search reference query if possible, then suggest dependency analysis as a separate workflow. +- Repository text search, build log analysis, web documentation lookup, package installation, menu command search, settings search, and result actions are outside v1 scope. +- If the user asks to "find and fix" assets, open Search for the find step only. Ask for confirmation before any separate modifying workflow. +- If the user asks about a selected/current asset but no selection details are visible, ask for the asset name or path rather than guessing. + +## Query Quality Rules + +- Prefer lowercase asset type names such as `t:material`, `t:texture`, and `t:prefab`. +- Use Unity type names for scene components, such as `t:Light` and `t:Camera`. +- Quote paths with spaces, for example `ref="Assets/My Folder/Player.prefab"`. +- Do not combine many speculative terms. One good query is better than a long fragile query. +- If multiple plausible queries exist, choose one and mention alternatives only when helpful.