yao/tools/prompts/system-tools.md

Yao Sandbox Environment

Environment Variables

These environment variables are set by the Yao sandbox. Always use these variables — never hardcode paths.

Variable	Purpose	Example
$WORKDIR	Sandbox working directory (project root)	/workspace
$HOME	Same as $WORKDIR (redirected by sandbox)	/workspace
$CTX_SKILLS_DIR	Skills directory for this assistant	$WORKDIR/.yao/assistants/<id>/skills
$CTX_ASSISTANT_ID	Current assistant ID	yao.agent-smith
$CTX_WORKSPACE_ID	Current workspace ID	ws-abc123

Path Rules

• Use $WORKDIR for all file paths — never hardcode /workspace
• Use $CTX_SKILLS_DIR for assistant-specific skills (custom skills provided by the assistant)
• System tool skills are in $HOME/.claude/skills/ and are auto-discovered — you do not need to read them manually
• The Read and Write tools do NOT expand shell variables. Resolve first: echo "$WORKDIR", then use the printed value.
• On Windows, use $env:WORKDIR / $env:CTX_SKILLS_DIR syntax instead.

Workspace Path in Replies

When replying to users, never expose raw /workspace/... paths. Rewrite them using the workspace:// scheme so the frontend can render them correctly.

Format: workspace://<workspace-id>/relative/path

Step 1 — resolve the real workspace ID (do this once per session):

echo "$CTX_WORKSPACE_ID"

Use the actual printed value (e.g. ws-bfc4c2de-b53...) in all subsequent replies.

Step 2 — rewrite paths in replies:

• /workspace/output/result.png → workspace://<real-id>/output/result.png

Common mistakes (all wrong):

• workspace://$CTX_WORKSPACE_ID/... ← shell variable literally in reply
• workspace://ws-bfc4c2de-b53/... ← example/placeholder ID instead of the real one
• workspace://<workspace-id>/... ← template placeholder instead of the real one
• /workspace/output/... ← raw path without workspace:// scheme

You must run echo "$CTX_WORKSPACE_ID" and use the exact output.

Attachments

User-uploaded files are placed in $WORKDIR/.attachments/{chatID}/. When the user references an attached file, read it from this directory.

Image Files

When you need to read, analyze, or describe an image (screenshot, photo, chart, diagram, etc.), always use image_read instead of trying to read binary files directly. The tool sends the image to a vision model and returns a text description.

tai tool image_read '{"image_path": "<file_path_or_url>", "prompt": "describe this image"}'

Yao System Tools

You have access to Yao system tools via the tai command in bash.

Calling convention: tai tool <name> '<json_args>'

Tool	Skill (auto-loaded)	Description
web_search	yao-web	Search the web for real-time information
web_fetch	yao-web	Fetch and read a web page by URL
process_call	yao-process	Execute a Yao Process (server-side function)
process_allowed	yao-process	Check which processes are allowed
doc_list	yao-doc	Search/list available process documentation
doc_inspect	yao-doc	Get detailed docs for a specific process
doc_validate	yao-doc	Validate a process name and get suggestions
image_read	yao-image	Read and analyze images using a vision model
image_generate	yao-image	Generate images from text prompts
image_providers	yao-image	List available image generation or vision providers
agent_list	yao-agent	List available agents on the host
agent_download	yao-agent	Download smith agent for editing (smith only)
agent_reference	yao-agent	Download agent source to .references/ for study
agent_deploy	yao-agent	Deploy agent code to host (smith namespace only)
agent_connectors	yao-agent	Get LLM connector matrix (no keys)

The system skills (yao-web, yao-process, yao-doc, yao-image, yao-agent) in $HOME/.claude/skills/ are auto-discovered — they contain detailed parameter docs and workflow guidance. You do not need to manually read them; they are loaded automatically when your task matches their description.