tool-reference
Skill3 starsChanged 3 months agoMITView on GitHub
Use when calling a Hades MCP tool and its terse tools/list description isn't enough — deeper per-tool detail, caveats, edge cases, and worked examples for graph_query, inspect_asset, find_unset_references, the batch apply/manage tools, and others. Load before a retry after an unexpected result, or when deciding between two similar tools.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- animation-workflowSkill
- component-designSkill
- data-modelingSkill
- prefab-architectureSkill
- prefab-workflowSkill
- scene-architectureSkill
- scene-authoringSkill
- unity-addressablesSkill
- unity-ai-behaviorSkill
- unity-architectSkill
- unity-audioSkill
- unity-ecsSkill
- unity-inputSkill
- unity-networkingSkill
- unity-performanceSkill
- unity-reviewerSkill
- unity-shaders-hdrpSkill
- unity-shaders-urpSkill
- unity-testingSkill
- unity-uiSkill
- unity-vfxSkill
- unity-workflowSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Every operation in the array is attempted in order.
- Very specific: line 15
Every successful operation's own result data (a new asset's guid, createLayer's assigned index, swapShader's …
- Very specific: line 53
If type isn't found at all, the most likely cause is that the defining script was just written or edited and the Editor hasn't compiled it …
- Very specific: line 61
Call find_references_to before deleting an asset other content may reference, and find_unset_references afterward to find the holes a …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hades Tool Reference
Hades' tools/list descriptions are kept short on purpose (payload size — an agent's context is spent on every tool on every turn). This skill holds the detail that was cut: rationale, edge cases, and vocabulary that matters less often than the description's core "what it does and how to call it." For known boundaries of what Hades can see at all (reflection, DI, dynamic instantiation, binary asset coverage, ...), see LIMITATIONS.md at the repo root — this skill does not repeat that page.
Batch tools: shared result shape
scene_apply, material_apply, prefab_apply, scriptable_object_apply, animation_apply, asset_manage, scene_manage, and project_settings_apply all share one contract, trimmed from each tool's own description to avoid repeating it eight times:
- Every operation in the array is attempted in order. An unrecognised
opvalue, or a field not valid for the op it's attached to, refuses the whole call before anything reaches the Editor — nothing partially applies from a malformed batch. - Once dispatched, failure is per-operation, not transactional: each op's outcome is reported by its 0-based index in
applied(succeeded) orfailed(with its own error). Operations that already succeeded are never rolled back because a later one failed — a partial result is a partially-applied batch, not an all-or-nothing unit. - Every successful operation's own result data (a new asset's
guid,createLayer's assignedindex,swapShader'ssurvivedProperties/lostProperties, ...) rides along inresults, alongside the bare index inapplied— never collapsed into a blanket success flag. - Undo coverage is uneven across tools and even across ops within one tool — see each tool's own section below before assuming one Ctrl/Cmd+Z reverts a whole batch.
graph_query
graph_query is Hades' single consolidated structured-search surface: every one-off "find X" question (orphan scripts, prefabs using a given component, assets of a given type, ...) is expressible as a combination of its filters rather than a dedicated tool. A few combinations are worth knowing by pattern:
- Finding scripts nothing references:
kind: "Class", edgeKind: "references", edgeDirection: "incoming", edgeAbsent: true. - Finding prefabs/scenes that use a given component type: a builtin kind matches directly (
kind: "Rigidbody"); a MonoBehaviour resolves viakind: "MonoBehaviour", edgeKind: "references", edgeTargetNamePattern: "<TypeName>", edgeTargetKind: "Class". - Finding every file that references one specific asset (e.g. everything using one script):
edgeKind: "references", edgeTargetPath: "<path>". - Whole-file classification (an asset's type as a FILE, not a graph node — the only way to enumerate every Scene/Prefab/ScriptableObject in the project):
fileType: "<Script|Scene|Prefab|Material|AnimatorController|ScriptableObject|Asset>", optionally withpathPrefix.
edgeAbsent is an honest superset, not confirmed-dead-code. edgeAbsent: true with edgeKind: "references", edgeDirection: "incoming" finds classes nothing references in the graph — but a class only ever instantiated from C# (AddComponent<T>(), new, a static utility call) has no incoming reference either, because code-level instantiation isn't tracked as a graph edge, only Unity YAML references are. Treat a hit as "worth checking by hand", not "safe to delete".
fileType answers a different question than kind. Script/Material/AnimatorController each map to exactly one node kind per file, so kind: "Class" mostly works for scripts — but Scene, Prefab, and ScriptableObject do not: a scene or prefab is many per-object nodes with no single summarising one, and a ScriptableObject instance shares MonoBehaviour's generic kind with an ordinary component. fileType sidesteps this by reading file identity instead of node identity — one hit per file, for any of the seven classified types — which is also why it's refused together with every node-level filter (kind, kindPattern, namePattern, edgeKind): mixing the two answers is a well-formed no-op, not a useful combination.
A ScriptableObject asset's graph kind is MonoBehaviour, not ScriptableObject. A .asset file is a !u!114 YAML document, identical in node shape to a component. graph_query(kind: "ScriptableObject") will never find one — use graph_query(fileType: "ScriptableObject") or search_by_name instead.
minWidth/minHeight silently exclude every texture whose header Hades could not read. They compare against the measured source dimensions, which are NULL for any format outside PNG/JPEG/TGA/PSD (see LIMITATIONS.md) — and NULL never satisfies >=. So {"kind": "Texture2D", "minWidth": 2049} means "every texture Hades could measure that is wider than 2048px", not "every texture wider than 2048px". To tell a genuine absence from an unmeasurable one, drop the dimension filter and call inspect_asset on the hits — an unreadable header reports its reason by name rather than guessing a size.
assetSubtype is an exact, case-sensitive match against the importer's own vocabulary. A texture's is Sprite/NormalMap/GUI/Default/…; a model's rig is Humanoid/Generic/Legacy/None. There is no substring form and no way to enumerate the set — call inspect_asset on one asset you know is of the kind you want and copy the assetSubtype string out of its introspection. A guessed casing ("sprite") is a well-formed query that matches nothing, not an error.
inspect_asset
guidis always present at the top level (from the file's.meta,nullif not yet imported) alongside whatever structure/material/controller payloadpathalone produced — identity is available even when a hierarchy is too.- For textures specifically,
maxTextureSizeinintrospectionis the import ceiling Unity was configured with, not the source image's actual size — a 64×64 icon and an 8192×8192 texture both report2048under default settings.sourceWidth/sourceHeightare the measured values read from the file's own header, and arenullfor a format Hades can't read a header from (seeLIMITATIONS.md's binary-header section for exactly which formats that covers). - A MonoBehaviour whose script guid doesn't resolve still appears in a
targetresult, with its raw guid andmissing: true, rather than being silently dropped. - A UnityEvent field's wired listeners (e.g. a Button's
m_OnClick) are reported even when a given listener's own target is itself unset. - A
propertyvalue that is itself a reference ({fileID, guid, type}) resolves to a project-relative path the same way top-level references always do; an unresolved external guid or Unity's own null reference is reported plainly, never as an error. - A legacy pre-2018.3
Prefab:YAML format file is reported as unsupported by name, not silently returned empty.
find_unset_references
- Every occurrence is reported unfiltered, because Unity's serialized YAML doesn't record why a reference is empty — a field deliberately left optional and one simply forgotten are byte-for-byte identical on disk, so Hades can't tell them apart and won't guess. A field whose name does not start with
m_is more likely a genuine, user-authored gap worth investigating first —m_-prefixed fields are Unity's own structural bookkeeping (e.g.m_Fatherunset on a root GameObject's Transform is correct: it has no parent). - Whole-project mode (
pathomitted) finds UnityEvent fields with at least one wired listener, graph-served — an event with zero listeners, or whose every listener has an unset target, leaves no trace and won't appear here.listenerCountis a lower bound, not always exact. Callinspect_assetwithtarget/componenton one specific component for the complete, exact picture instead.
scriptable_object_apply
- If
typeisn't found at all, the most likely cause is that the defining script was just written or edited and the Editor hasn't compiled it yet: callproject_recompile_scripts, pollhades_charon_statusuntil it reports attached, then retry. [CreateAssetMenu]is ignored entirely — not consulted for gating, defaults, or validation.- Undo destroys
create's in-memory object but leaves the.assetfile it wrote on disk. Re-running an identical batch after a partial failure will fail atcreatewith "already exists" (the file from the first attempt is still there) — drop thecreateop and re-runsetPropertiesalone, or delete the asset first withasset_manage. - The resulting asset's graph Kind is
MonoBehaviour, notScriptableObject— see thegraph_querysection above.
asset_manage
deletemoves the asset to the OS trash/recycle bin, never a permanent delete — recoverable outside Hades on macOS/Windows; Linux/headless recoverability is unverified. It refuses folders outright (delete their contents instead) and reportsfailed, never a false success, if the underlying move-to-trash call itself fails (a locked file, a VCS hold, ...) — nothing is deleted in that case.- Call
find_references_tobefore deleting an asset other content may reference, andfind_unset_referencesafterward to find the holes a delete left behind. duplicateregisters Undo for the new in-memory copy, but Ctrl/Cmd+Z only destroys that in-memory object — the copied file stays on disk, so finish undoing a duplicate with adeleteop on the copy.
prefab_apply
editPropertyis atomic (load, edit, save in one step) — there's no separateopen/savepair, so this tool cannot leave a prefab stuck open the way an old open→edit→save sequence could. Changing several properties on the same prefab in one call means severaleditPropertyops, not one op with multiple values.- The whole batch acquires and releases Unity's reload lock exactly once, not once per operation — prefab operations are lease-bounded, unlike scene/material/animation's lease-free class.
applyOverridesalways reportsunappliedPropertiesin its own result:PrefabUtility.ApplyPrefabInstancecan never write a prefab instance root's own name/position/rotation back to the prefab asset — this is permanent Unity behaviour, not an error, so checkresults, never assumeappliedalone means everything was written.
material_apply
swapShaderreportssurvivedProperties/lostPropertiesin its own result — Unity silently drops any shader property the new shader doesn't declare, by name and type, and this is the only way to find out which values just vanished.- Undo destroys
create/duplicate's in-memory Material object but leaves the.matfile on disk — same pattern asscriptable_object_applyandasset_manage'sduplicateabove.
project_settings
"layers"returns all 32 slots by index, 0–31; an unused slot is a real, meaningful empty string at its own index, never omitted or compacted. Layer 8 being free is not the same as "layers end at 7" — always read by index, never assume the array truncates at the first gap."buildScenes": each entry'senabledflag means actually included in a build, not merely present in the Build Settings list."renderPipeline"reports"unknown"only when a custom pipeline is configured but can't be positively identified — never guessed from a partial match, since Built-in/URP/HDRP differ enough that a guess would sometimes just be wrong.
get_project_summary
appliedDefinesis built fromUNITY_EDITOR, the Unity-version ladder read fromProjectVersion.txt, the project's ownscriptingDefineSymbols, and every asmdefversionDefinewhose named package resolves to a satisfying version — the same set project-wide, for every file. This is an approximation: Unity's real compiler uses a different set per assembly (asmdef), and Hades doesn't yet track file-to-asmdef membership. Code gated on a symbol outside this list (a platform define, a csc.rsp-only symbol, or a versionDefine keyed to a built-in Unity module rather than an installed package) is invisible to the graph entirely — not a false negative in a query, just absent.
hades_rebuild_graph
- Waits its turn behind any other indexing already running for this project before it starts running itself.
- Hades' incremental sync already keeps the graph current on its own during normal use — call this only when you suspect the graph has actually drifted from disk, not as routine maintenance.
hades_regression
- A tool whose result varies between calls (a timestamp, an uptime counter — e.g.
hades_ping) replays as a mismatch every time underexpectedcomparison; such tools make poor fixture entries foraction='replay'.
trace_dependencies
- Walks
referencesandinstance_ofedges outward;corresponds_tois deliberately excluded from the walk because every nested prefab instance that writes acorresponds_toedge also writes aninstance_ofedge to the same file, so including both would just duplicate hits.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

