unity-behavior
Drive Unity Behavior behavior graphs and blackboard variables
Install / Use
npx skills add Besty0728/Unity-Skills --skill behaviorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Tags
Our assessment of unity-behavior
unity-behavior scores 86/100 on our quality scale, 720th of 1,155 Content & Media skills we index.
Its SKILL.md is 12 KB long, well organised into 22 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
With 1,781 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so unity-behavior is actively maintained.
- Our last check on 2026-11-03 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
unity-behavior compared with similar skills
All 4 of these similar skills score higher than unity-behavior; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| unity-behavior (this skill)by Besty0728 | 86 | 1.8k | 53d ago | SKILL.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install unity-behavior?
- Run
npx skills add Besty0728/Unity-Skills --skill unity-behavior. The install tabs above show the steps for each supported agent. - Which AI agents does unity-behavior work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is unity-behavior safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is unity-behavior still maintained?
- The repository was last updated about 2 months ago, so unity-behavior is actively maintained.
Skill content
View source on GitHubname: unity-behavior description: Drive Unity Behavior behavior graphs and blackboard variables
Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via
GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Triggers
- Wiring NPC/AI decision logic
- Working with behavior trees/graphs
- Reading/writing blackboard variables
- 搭建 NPC/AI 决策逻辑、使用行为树/行为图、读写黑板变量
Behavior Skills
Unity Behavior (com.unity.behavior, validated against 1.0.16) graph asset discovery, agent wiring, and blackboard variable access.
The package is optional and is not a declared dependency of UnitySkills. Every skill in this module reaches it through reflection; when it is absent each skill returns the same structured PACKAGE_NOT_INSTALLED response pointing at package_install.
Operating Mode
- Query skills (
behavior_status,behavior_graph_list,behavior_graph_info,behavior_agent_get,behavior_agent_list,behavior_blackboard_list) areSkillMode.SemiAuto— they run in all three modes without a grant. - Mutators (
behavior_graph_create,behavior_agent_add,behavior_agent_set_graph,behavior_blackboard_set) areSkillMode.FullAuto— under Approval they need a user grant; under Auto / Bypass they execute directly. - No skill in this module carries
SkillOperation.Delete, so none is auto-forbidden in Approval / Auto mode.
Prerequisites
Install the package first if behavior_status reports installed: false:
package_install packageName="com.unity.behavior"
Installation triggers a Domain Reload; wait for it to finish, then call behavior_status again before using any other skill in this module.
The two asset types (read this before binding graphs)
A "Behavior Graph" .asset file contains two objects, and mixing them up is the most common failure:
| Object | Role | Where it lives |
|--------|------|----------------|
| BehaviorAuthoringGraph | Editing representation — nodes, blackboard, story. Main asset. | The .asset file itself |
| BehaviorGraph | Baked runtime graph. What BehaviorGraphAgent.Graph actually requires. | Sub-asset nested inside the same file |
Skills in this module always take the file path (graphAssetPath / assetPath) and resolve the correct object internally — you never address the sub-asset directly. behavior_agent_set_graph finds the nested BehaviorGraph for you and refuses the bind with RUNTIME_GRAPH_MISSING when the graph has never been compiled.
Guardrails
Routing:
- Behavior graphs / blackboards /
BehaviorGraphAgent: this module - Animator state machines: use
animator_* - Generic component attach on a GameObject:
component_addworks, butbehavior_agent_addadditionally binds the graph and validates it
Runtime-first rules:
- Always call
behavior_blackboard_listbeforebehavior_blackboard_set— the variable name is case-sensitive and the declared CLR type decides which value shapes are accepted. - Never invent a
graphAssetPathfrom memory; get it frombehavior_graph_list. - If a skill returns
errorCode: "API_MISMATCH", the installed package version has a different member layout than this integration expects. Do not retry with different arguments — report the version mismatch and fall back to the Behavior editor window or direct.assettext editing. - A graph created by
behavior_graph_createis empty apart from the auto-insertedStartroot. Adding actual behavior nodes requires the Behavior editor window (see Limitations).
Skills
behavior_status
Report package availability: installed, version, which core types resolved, project graph asset count, and scene agent count. Safe to call when the package is missing — this is the one skill that answers instead of erroring.
behavior_graph_list
List behavior graph assets with path, guid, nodeCount, variableCount, and hasRuntimeGraph. Optional filter (substring on path), folder, limit.
behavior_graph_info
Structure summary for one graph asset: node count with a per-type breakdown, individual nodes (id / type / position, capped by maxNodes), root count, the full blackboard variable list with types and default values, subgraph dependencies, and runtime graph state.
behavior_graph_create
Create an empty BehaviorAuthoringGraph at savePath and force a reimport so Unity bakes the blackboard, the runtime BehaviorGraph sub-asset, the debug info sub-asset, and the mandatory Start root. Returns hasRuntimeGraph; a warning is returned when baking did not happen and the graph must be opened once in the editor window.
behavior_agent_add
Add a BehaviorGraphAgent to a GameObject (name / instanceId / path), optionally binding graphAssetPath in the same call. The graph is resolved and validated before the component is added, so a bad path never leaves a half-configured agent. Idempotent — an existing agent is reused and reported via componentAdded: false.
behavior_agent_get
Read one agent: bound graph name and asset path, isInitialised / isStarted / isRunning, the graph's blackboard variables, and the agent-level overrides.
behavior_agent_set_graph
Bind graphAssetPath to an existing agent. Resolves the nested runtime graph and rejects uncompiled graphs.
behavior_agent_list
Every BehaviorGraphAgent in the loaded scenes with hierarchy path, bound graph, active/enabled flags, and run state. Optional graphFilter, includeInactive, limit.
behavior_blackboard_list
List blackboard variables. Pass graphAssetPath to read the asset's authoring defaults (source: "asset"), or a GameObject locator to read an agent's graph variables plus its overrides (source: "agent"). One of the two is required.
behavior_blackboard_set
Set one variable value.
| Parameter | Meaning |
|-----------|---------|
| variable | Variable name, case-sensitive. Required. |
| value | New value. Accepted shapes depend on the declared type (see below). |
| name / instanceId / path | GameObject locator — writes the agent-level override. |
| graphAssetPath | Writes the graph asset default and rebakes the runtime blackboard. |
Provide either the GameObject locator or graphAssetPath; the GameObject wins if both are given.
Returns: target ("agent" or "asset"), variable, type, the normalized value, and a note explaining where the write landed.
Supported value types and accepted input shapes:
| Declared type | Accepted value |
|---------------|------------------|
| int / float / double / bool / string | JSON scalar, or a parseable string |
| enum | Member name (case-insensitive) |
| Vector2 / Vector3 / Vector4 / Quaternion | [1,2,3], {"x":1,"y":2,"z":3}, or "1,2,3" |
| Color | {"r":1,"g":0,"b":0,"a":1}, [1,0,0,1], or "#FF0000" |
| Vector2Int / Vector3Int | Same as the float vectors, truncated |
| GameObject / Component | Assets/... prefab path, scene hierarchy path, or scene object name |
| Other UnityEngine.Object | Assets/... or Packages/... asset path |
Setting an unknown variable returns the available names in availableVariables.
Edit mode vs Play mode
BehaviorGraphAgent instantiates a private copy of its graph on Init(), which only happens in Play mode. This changes what reads and writes mean:
- Edit mode —
behavior_blackboard_setwith a GameObject writes an agent-level override (exactly what the Inspector shows). Reads of the graph variables return the shared asset defaults, not per-agent values; the per-agent values are in theoverridesarray. - Play mode — writes go to the running graph instance, so they take effect immediately on that agent only.
This is why behavior_blackboard_list reports both variables and overrides for an agent.
Workflow
behavior_status— confirm the package is installed.behavior_graph_list— locate the graph, orbehavior_graph_createto make a new one.- Author the node graph in the Behavior editor window (node editing is not scriptable — see Limitations).
behavior_graph_info— confirm the node topology and read the blackboard contract.behavior_agent_addwithgraphAssetPath— attach and bind in one call.behavior_blackboard_list— read the exact variable names and declared types.behavior_blackboard_set— per-agent overrides, or graph-wide defaults viagraphAssetPath.behavior_agent_list— verify the whole scene's agent wiring.
Limitations
Node-level graph editing is not supported. There is no skill to add, remove, connect, or reconfigure nodes inside a behavior graph. This is a deliberate exclusion, not an oversight:
- The authoring node graph is stored as a
[SerializeReference]polymorphicList<NodeModel>withPortModelcross-references, an embeddedSerializableCommandBuffer, and a version-stampedNodeModelInfocache. Writing it correctly means reproducing the package's command/dispatcher pipeline, not just setting fields. - Every edit must be followed by a consistent rebake of three sub-assets (runtime graph, runtime blackboard, debug info) plus
VersionTimestampsynchronization, or the asset silently desyncs from its baked runtime graph. - The serialization schema is explicitly versioned (
kLatestSerializationVersion, currently 3) and has changed within the 1.0.x line. Reflection-driven topology writes would break on a patch release.
Alternatives when you need node-level changes:
- Preferred — author the graph in the Behavior editor window (
Window > AI > Behavior, or double-click the asset), then use this module to inspect and wire it up. - Duplicate a known-good graph with
asset_duplicateand rebind it, instead of building topology from nothing. - For mechanical, repetitive edits to an existing graph, edit the
.assetYAML directly — load the yaml-editing advisory first for the managed-reference andfileIDrules, and re-verify withbehavior_graph_infoafterwards.
Other limitations:
behavior_graph_createproduces an empty graph. Node authoring still requires the editor window.- Blackboard variables cannot be created, renamed, retyped, or deleted — only existing variables can be assigned. Add variables in the Behavior editor's Blackboard panel.
- Event channels, subgraph dynamic linking, and runtime serialization (
Serialize/Deserialize) are not exposed. behavior_blackboard_setagainstgraphAssetPathchanges the shared default for every agent that has no override for that variable.- Agent lifecycle control (
Init/Start/End/Restart) is not exposed; those are Play-mode runtime concerns better handled from game code.
Version Sensitivity
Type and member names were taken from com.unity.behavior 1.0.16 sources and cross-checked against the published Scripting API. Public surface (BehaviorGraphAgent, BehaviorGraph, BlackboardReference, Blackboard, BlackboardVariable, VariableModel) is documented and stable. Authoring surface (BehaviorAuthoringGraph, GraphAsset, BlackboardAsset, BehaviorBlackboardAuthoringAsset) is internal to the package and reached by name — a package upgrade can move it. Every such lookup is null-checked and reports API_MISMATCH rather than throwing; behavior_status shows exactly which types resolved.
Exact Signatures
Exact names, parameters, defaults, and returns are defined by GET /skills/schema or unity_skills.get_skill_schema(), not by this file.
Related Skills
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
