菜单
Guide for developing LLM agents based on PuerTsAgent framework — covers resource directory structure, system-prompt, skills, builtin modules, and best practices.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Tencent/puerts --skill puerts-interop命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | PuerTS Agent Development Guide |
| description | Guide for developing LLM agents based on PuerTsAgent framework — covers resource directory structure, system-prompt, skills, builtin modules, and best practices. |
This skill provides the complete guide for developing LLM agents based on the PuerTsAgent framework.
⚠️ Important — Required Packages: This framework depends on PuerTS core, v8, and agent packages. Before proceeding, you must check the Unity project's
Packages/manifest.jsonto verify that the following packages are installed:
com.tencent.puerts.corecom.tencent.puerts.v8com.tencent.puerts.agentIf any of these packages are missing, they must be installed first before using this skill. you MUST first invoke the "Install PuerTS for Unity" skill to AUTO complete the setup.
⚠️ Prerequisite: Before using this skill to create or modify an agent, you must know the agent's resource directory path under Unity
Resources/(e.g.,maze-runner,editor-assistant). If the user has not provided this path, ask the user whichResources/subdirectory to use before proceeding. All agent files (system-prompt, skills, builtins) are organized under this path.
⚠️ Builtin Language Choice: When creating builtin modules, you must ask the user whether they want to write builtins in TypeScript or JavaScript:
- TypeScript → Create a dedicated TS project (with , , ) whose build output () points to . See section below.
package.jsontsconfig.jsonesbuild.mjsoutdirAssets/Resources/<agent-name>/builtins/.mjs files directly in Assets/Resources/<agent-name>/builtins/.In this framework, an agent's behavior and capabilities are entirely defined by files in a resource directory (Resource Root). Different resource directories represent different agents — Unity editor assistants, in-game AI characters, or any role you need.
Key Concept: Both
system-prompt.md.txtand files underskills/are essentially prompts (natural language instructions for the LLM). The only difference is their loading strategy:
system-prompt.md.txt— Always present in context (persistent). Put prompts here that are needed for most tasks.skills/*.md.txt— Loaded on demand by the LLM vialoadSkill. Put prompts here that are not needed for every task — they are loaded only when the LLM determines they are relevant.
Initialize an agent in C# via its resource path:
var agent = new AgentScriptManager();
agent.Initialize("maze-runner", () =>
{
Debug.Log("Maze runner agent is ready!");
});
The first parameter of Initialize is the resource directory path under Unity Resources/. The framework loads the full agent definition from this directory:
system-prompt.md.txt — Role definition (System Prompt)skills/ — Domain skill documents (loaded on demand, optional)builtins/ — Built-in helper modules (executable JS modules)Resources/maze-runner/
├── system-prompt.md.txt # Role definition (System Prompt)
├── skills/ # Domain skills (loaded on demand, optional)
└── builtins/ # Built-in modules (loaded on demand)
├── maze-control.mjs # Maze movement and status query
└── screenshot.mjs # Screenshot to observe the maze
All resource files are placed in Unity's Resources/ directory.
File extension convention: Unity
Resourcesdoes not support.mdand.mjsas TextAsset, so:
- Markdown files use
.md.txtsuffix- JS module files use
.mjssuffix
system-prompt.md.txt defines the agent's identity, personality, capabilities, and behavioral rules. It is injected at the beginning of the LLM's system prompt and is the core of the agent's "persona."
This is a persistent prompt — it is always present in the LLM's context for every conversation turn. Therefore, put only the most frequently used instructions here — things the agent needs for the majority of its tasks. Avoid stuffing rarely-used domain knowledge here, as it permanently consumes context tokens.
<resource-root>/system-prompt.md.txt
Plain text / Markdown format, write role definition directly, no front-matter needed.
You are a helpful AI assistant running inside Unity via PuerTS (a TypeScript/JavaScript runtime for Unity). You can help with game development, scripting, and general questions. Be concise and practical.
You are a Maze Explorer AI — an intelligent agent that navigates through 3D mazes by observing, reasoning, and acting.
## Your Capabilities
You can control a player character in a 3D maze using two builtin modules:
- **maze-control**: Move in compass directions (north/south/east/west) with `movePath()` and query obstacle distances with `getPlayerStatus()`
- **screenshot**: Capture the game view to visually observe the maze
## Goal Description
Your goal is to reach the **maze exit marker** — a tall RED pillar with a bright RED glowing ring.
The System Prompt describes the AI's identity, available modules, goals, exploration loops, navigation rules, etc. It can be lengthy — it defines the AI's behavior pattern throughout the task.
A Skill is an on-demand loaded Markdown document providing domain-specific operation guides and rules for the LLM. The LLM actively loads skills into context via the loadSkill tool when needed.
Skills are prompts too — just like
system-prompt.md.txt, they are natural language instructions. The key difference is that skills are not always in context. If a piece of knowledge is not needed for most tasks the agent handles, it belongs in a skill file rather than in the system prompt. This keeps the base context lean while still making specialized knowledge available when the LLM needs it.
<resource-root>/skills/<skill-name>.md.txt
Skill files use YAML front-matter for metadata, body is Markdown content:
---
name: <skill-id>
description: "<one-line description shown to the LLM>"
---
(Markdown body — the actual skill instructions)
| Front-matter Field | Required | Description |
|---|---|---|
name | ✅ | Unique identifier, LLM calls loadSkill with this name |
description | ❌ | Short description shown in loadSkill available skills list |
skills/puerts-interop.md.txt:
---
name: puerts-interop
description: "PuerTS JS ↔ C# interop rules: CS/puer globals, out/ref params, generics, operators, Array/List indexer access, async/Task."
---
## PuerTS: JS ↔ C# Interop Rules
...
system-prompt.md.txt. Otherwise → put it in skills/ for on-demand loadingBuiltin modules are JavaScript modules providing pre-built helper functions for the LLM's evalJsCode tool. Unlike Skills, Builtins are actually executable code, not documentation.
<resource-root>/builtins/<module-name>.mjs
Source code can use TypeScript, JavaScript, or any language compilable to
.mjs. The framework only cares about the final.mjsfiles in the resource directory.
Every Builtin module must export the following two string constants:
| Export | Type | Description |
|---|---|---|
summary | string | Short summary (~one line), always shown in evalJsCode tool description |
description | string | Detailed function signatures and usage, LLM reads via import() |
Additionally, the module's exported functions are the actual capabilities the LLM can call in evalJsCode.
builtins/unity-log.mjs (shown as TypeScript source)// ---- Summary for tool description (always in context) ----
export const summary = `**unity-log** — Unity console log access (retrieve and summarize recent logs). Read \`.description\` to see available functions and their signatures.`;
// ---- Description for on-demand access via import ----
export const description = `
- **\`getUnityLogs(count?, logType?)\`** — Get recent Unity console logs.
- \`count\` (number, default 20): Number of log entries to retrieve (1-50).
- \`logType\` (string, default \`'all'\`): Filter by type — \`'all'\`, \`'error'\`, \`'warning'\`, or \`'log'\`.
- Returns an array of log entry objects: \`{ timestamp, type, message, stackTrace? }\`.
`.trim();
// ---- Function implementations ----
export function getUnityLogs(count: number = 20, logType: string = 'all'): LogEntry[] {
const logsJson = CS.LLMAgent.UnityLogBridge.GetRecentLogs(count, logType);
return JSON.parse(logsJson);
}
builtins/maze-control.mjs (TypeScript source, excerpt)export const summary = `**maze-control** — Control the player in the maze. \`movePath([{dir, steps}, ...])\` executes a multi-segment path. \`getPlayerStatus()\` returns position and obstacle distances. Read \`.description\` for details.`;
export const description = `
- **\`movePath(segments)\`** — Move the player along a multi-segment planned path.
- \`segments\` (array): Array of \`{ dir: string, steps: number }\`.
- Returns: \`{ success, stepsCompleted, blocked, reachedGoal, position, message }\`
- **\`getPlayerStatus()\`** — Get the player's position and obstacle distances.
- Returns: \`{ position, northDistance, southDistance, eastDistance, westDistance, reachedGoal }\`
`.trim();
export async function movePath(segments: PathSegment[]): Promise<MoveSequenceResult> {
const directionsJson = JSON.stringify(segments.map(s => s.dir));
const distancesJson = JSON.stringify(segments.map(s => s.steps));
const resultJson = await new Promise<string>((resolve, reject) => {
CS.LLMAgent.MazePlayerBridge.MoveSequenceV2(directionsJson, distancesJson, (json: string) => resolve(json));
});
return JSON.parse(resultJson);
}
export async function getPlayerStatus(): Promise<PlayerStatusResult> {
const resultJson = await new Promise<string>((resolve, reject) => {
CS.LLMAgent.MazePlayerBridge.GetPlayerStatus((json: string) => resolve(json));
});
return JSON.parse(resultJson);
}
await at top level (e.g., async initialization)Resources/<agent-name>/
├── system-prompt.md.txt
├── skills/
└── builtins/
Edit system-prompt.md.txt to define the AI's identity and behavioral rules. For example, a maze AI should describe:
Create .md.txt files in the skills/ directory with YAML front-matter and skill content.
The Maze Demo doesn't use skill files — all navigation rules are directly in system-prompt. When domain knowledge is extensive and doesn't need to be loaded every time, splitting into skills is more appropriate.
First, ask the user whether to write builtins in TypeScript or JavaScript:
Resources/<agent-name>/builtins/..mjs files directly in Assets/Resources/<agent-name>/builtins/.In C# code, initialize the agent with the corresponding resource path (see "Creating an Agent" section above).
When the user chooses TypeScript for builtins, create a dedicated TS project with the following structure and files. Replace <agent-name> with the actual agent name (e.g., maze-runner).
Ts<AgentNamePascalCase>/ # e.g., TsMazeRunner/
├── package.json
├── tsconfig.json
├── esbuild.mjs # Build script — outputs to Resources/<agent-name>/builtins/
└── src/
└── builtins/
└── <module-name>.mts # TypeScript source files
{
"name": "<agent-name>",
"version": "1.0.0",
"description": "<Agent description> - TypeScript builtins",
"private": true,
"scripts": {
"build": "node esbuild.mjs",
"typecheck": "tsc --noEmit"
},
"devDependencies": {
"esbuild": "^0.25.0",
"typescript": "^5.4.0"
}
}
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"moduleResolution": "nodenext",
"rootDir": "src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": false,
"sourceMap": false,
"noEmit": true,
"typeRoots": ["../Assets/Gen/Typing", "../puerts/unity/upms/core/Typing"]
},
"include": ["src/**/*.mts", "src/**/*.d.ts", "../Assets/Gen/Typing/csharp/index.d.ts"],
"exclude": ["node_modules"]
}
import { build } from 'esbuild';
import { readdirSync, mkdirSync, existsSync } from 'fs';
import { join } from 'path';
// Build <agent-name> builtins modules
const builtinSrcDir = 'src/builtins';
const builtinOutDir = '../Assets/Resources/<agent-name>/builtins';
const builtinFiles = existsSync(builtinSrcDir)
? readdirSync(builtinSrcDir).filter(f =>
f.endsWith('.mts') && !f.endsWith('.d.mts'))
: [];
if (builtinFiles.length > 0) {
if (!existsSync(builtinOutDir)) {
mkdirSync(builtinOutDir, { recursive: true });
}
const builtinEntries = builtinFiles.map(f => join(builtinSrcDir, f));
await build({
entryPoints: builtinEntries,
bundle: true,
format: 'esm',
outdir: builtinOutDir,
outExtension: { '.js': '.mjs' },
platform: 'neutral',
target: 'esnext',
sourcemap: false,
minify: false,
keepNames: true,
external: [],
define: {
'process.env.NODE_ENV': '"production"',
},
});
console.log(`[esbuild:<agent-name>] Built ${builtinFiles.length} builtins module(s) → ${builtinOutDir}/`);
} else {
console.log('[esbuild:<agent-name>] No builtins modules found in src/builtins/');
}
After creating the project files:
npm install in the project directory to install dependencies.mts source files in src/builtins/npm run build to compile and output .mjs files to Assets/Resources/<agent-name>/builtins/npm run typecheck for type checking (optional but recommended)