nex-agi/nexau-agent

NexAU Agent Builder

This skill provides the procedural knowledge and reference material needed to implement NexAU agents correctly and efficiently.

When to Use

• Implementing a new standalone agent (YAML config + system prompt + tools + entry point)
• Adding custom tools to an existing agent
• Writing or refining system prompts for NexAU agents
• Setting up skills for an agent
• Looking up NexAU framework concepts (agents, tools, LLMs, transports, sessions, etc.)

NexAU Documentation: The docs/ directory contains the full user-facing documentation for NexAU. Start with docs/index.md for an overview, docs/getting-started.md for setup, docs/core-concepts/ for fundamentals (agents, tools, LLMs), and docs/advanced-guides/ for topics like skills, hooks, MCP, sandbox, transports, and session management.

Agent Implementation Workflow

1. Understand the Requirements

Before writing any code, read the RFC or requirements document thoroughly. Identify:

• Agent purpose and capabilities
• Required tools (builtin vs custom)
• LLM configuration needs (model, temperature, token limits)
• Any skills the agent should have

2. Create the Directory Structure

A standalone agent follows this layout:

agent_name/
├── agent_name.yaml          # Agent configuration
├── systemprompt.md           # System prompt (Jinja2 or plain string)
├── start.py                  # Entry point script
├── tools/                    # Tool definitions
│   ├── read_file.tool.yaml
│   ├── write_file.tool.yaml
│   └── custom_tool.tool.yaml
├── skills/                   # Optional skills
│   └── skill-name/
│       └── SKILL.md
└── custom_tools/             # Custom tool implementations (if any)
    └── custom_tool.py

3. Write the Agent YAML Config

Refer to references/agent-yaml-reference.md for the complete field reference. Key points:

• Use ${env.VAR_NAME} for environment variable substitution (LLM keys, sandbox paths)
• Set system_prompt_type: jinja when using template variables like {{ date }}
• Set system_prompt_type: string for plain text prompts
• Choose tool_call_mode: structured for provider-native structured tool calling
• Reference tool YAMLs with relative paths: ./tools/tool.tool.yaml
• Reference system prompt with relative path: ./systemprompt.md

Template available at: assets/templates/agent.yaml

4. Define Tools

For each tool the agent needs:

1. Check if a builtin tool exists — see references/builtin-tools-reference.md
2. If builtin, copy the tool YAML from an existing example and set the binding path
3. If custom, create both a .tool.yaml definition and a Python implementation

Refer to references/tool-yaml-reference.md for the tool YAML schema.

Template available at: assets/templates/tool.tool.yaml

5. Write the System Prompt

Follow the conventions in references/system-prompt-guide.md:

• Start with a clear role description
• Define a numbered step-by-step workflow
• Include guidelines and constraints
• Add template variables at the bottom: {{ date }}, {{ username }}, {{ working_directory }}

Template available at: assets/templates/systemprompt.md

6. Create the Entry Point

For standalone agents, use Agent.from_yaml().

Template available at: assets/templates/start.py (standalone)

7. Verify the Implementation

• Validate agent config:

  python {THIS_SKILL_FOLDER}/scripts/validate_agent.py path/to/agent.yaml
  

  • Add --recursive to also validate sub-agent configs
  • Add --json for machine-readable output
• Check Python syntax: python -c "import ast; ast.parse(open('start.py').read())"
• Check imports: python -c "from nexau import Agent"
• Run the agent with a simple test query

Common Patterns

Environment Variable Substitution in YAML

llm_config:
  model: ${env.LLM_MODEL}
  base_url: ${env.LLM_BASE_URL}
  api_key: ${env.LLM_API_KEY}

Adding Builtin Tools

tools:
  - name: read_file
    yaml_path: ./tools/read_file.tool.yaml
    binding: nexau.archs.tool.builtin.file_tools:read_file

Adding Skills

skills:
  - ./skills/skill-name

Stop Tools

Use stop_tools to define tools that halt the agent loop when called:

stop_tools: [complete_task]    # For task-based agents
stop_tools: [ask_user]         # For interactive agents

Tracers

tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer

Builtin Tools Catalog

All builtin tool YAML configs are located under builtin_tools/tools/ in this skill folder. When adding a builtin tool to an agent, copy the YAML to your agent's tools/ directory and set the binding path accordingly.

File Tools

| Tool | Binding | Config YAML | |------|---------|-------------| | read_file | nexau.archs.tool.builtin.file_tools:read_file | builtin_tools/tools/read_file.tool.yaml | | write_file | nexau.archs.tool.builtin.file_tools:write_file | builtin_tools/tools/write_file.tool.yaml | | replace | nexau.archs.tool.builtin.file_tools:replace | builtin_tools/tools/replace.tool.yaml | | search_file_content | nexau.archs.tool.builtin.file_tools:search_file_content | builtin_tools/tools/search_file_content.tool.yaml | | glob | nexau.archs.tool.builtin.file_tools:glob | builtin_tools/tools/Glob.tool.yaml | | list_directory | nexau.archs.tool.builtin.file_tools:list_directory | builtin_tools/tools/list_directory.tool.yaml |

Web Tools

| Tool | Binding | Config YAML | |------|---------|-------------| | google_web_search | nexau.archs.tool.builtin.web_tools:google_web_search | builtin_tools/tools/WebSearch.tool.yaml | | web_fetch | nexau.archs.tool.builtin.web_tools:web_fetch | builtin_tools/tools/WebFetch.tool.yaml |

Shell Tools

| Tool | Binding | Config YAML | |------|---------|-------------| | run_shell_command (sync) | nexau.archs.tool.builtin.shell_tools:run_shell_command | builtin_tools/tools/run_shell_command_sync.tool.yaml |

Session Tools

| Tool | Binding | Config YAML | |------|---------|-------------| | write_todos | nexau.archs.tool.builtin.session_tools:write_todos | builtin_tools/tools/write_todos.tool.yaml | | complete_task | nexau.archs.tool.builtin.session_tools:complete_task | builtin_tools/tools/complete_task.tool.yaml | | ask_user | nexau.archs.tool.builtin.session_tools:ask_user | builtin_tools/tools/ask_user.tool.yaml |

For detailed parameter descriptions of each tool, see references/builtin-tools-reference.md.

Bundled Resources

| Path | Purpose | |------|---------| | references/agent-yaml-reference.md | Complete agent YAML config field reference | | references/tool-yaml-reference.md | Tool YAML definition schema and examples | | references/builtin-tools-reference.md | Catalog of all builtin tools with binding paths | | references/system-prompt-guide.md | System prompt writing conventions and patterns | | assets/templates/agent.yaml | Starter agent YAML config template | | assets/templates/tool.tool.yaml | Starter tool YAML definition template | | assets/templates/systemprompt.md | Starter system prompt template | | assets/templates/start.py | Standalone agent entry point template | | scripts/validate_agent.py | Agent YAML validator (schema + file reference checks) | | docs/index.md | NexAU documentation index — entry point for all user-facing docs | | docs/getting-started.md | Installation, setup, and first agent walkthrough | | docs/core-concepts/agents.md | Agent architecture, lifecycle, and configuration | | docs/core-concepts/tools.md | Tool system — definition, binding, execution | | docs/core-concepts/llms.md | LLM provider configuration and aggregator usage | | docs/advanced-guides/skills.md | Skill system — folder-based and tool-based skills | | docs/advanced-guides/hooks.md | Hook system for lifecycle event handling | | docs/advanced-guides/mcp.md | Model Context Protocol integration | | docs/advanced-guides/sandbox.md | Sandbox configuration and isolation | | docs/advanced-guides/session-management.md | Session persistence and history management | | docs/advanced-guides/streaming-events.md | Streaming event types and handling | | docs/advanced-guides/transports.md | Transport layer — HTTP, stdio, WebSocket, gRPC | | docs/advanced-guides/templating.md | Jinja2 templating in system prompts and configs | | docs/advanced-guides/context_compaction.md | Context compaction middleware for long conversations | | docs/advanced-guides/global-storage.md | Global storage for cross-turn agent state | | docs/advanced-guides/tracer.md | Tracing and observability setup | | docs/advanced-guides/image.md | Image input handling |

Setting Up Skills for an Agent

Skills are reusable capabilities that extend an agent's knowledge and workflows. NexAU supports two types: folder-based skills and tool-based skills. Both are automatically registered and discoverable via the LoadSkill tool at runtime.

Folder-Based Skills

A folder-based skill is a self-contained directory with a SKILL.md file. To add one to an agent:

1. Create the skill directory under the agent's skills/ folder:

skills/
└── my-skill/
    ├── SKILL.md              # Required — metadata + instructions
    ├── scripts/              # Optional — executable code
    ├── references/           # Optional — context docs loaded on demand
    └── assets/               # Optional — templates, images, output files

2. Reference the skill in the agent YAML:

skills:
  - ./skills/my-skill

The agent will see a brief description of the skill in its system prompt and can call LoadSkill to read the full SKILL.md content when needed.

Tool-Based Skills

A tool-based skill is a regular tool marked with as_skill: true in its YAML definition. This is useful for simple, well-defined capabilities that do not need extensive documentation.

# tools/generate_code.tool.yaml
type: tool
name: generate_code
description: Generates code based on specifications
as_skill: true
skill_description: Code generation skill for multiple programming languages
input_schema:
  type: object
  properties:
    language:
      type: string
    specification:
      type: string
  required: [language, specification]

The skill_description field is required when as_skill: true. It provides the brief text shown in the skill registry.

Combining Both Types

Both skill types can coexist in the same agent:

# Agent YAML
skills:
  - ./skills/data-analysis       # Folder-based skill
  - ./skills/report-writing      # Folder-based skill

tools:
  - name: web_search
    yaml_path: ./tools/web_search.tool.yaml   # Tool-based skill (as_skill: true)
    binding: nexau.archs.tool.builtin.web_tools:google_web_search

How Skills Work at Runtime

1. All skills are registered in the agent's skill_registry during initialization
2. A LoadSkill tool is automatically added to the agent
3. The agent sees brief descriptions of all available skills in its system prompt
4. When the agent needs detailed information, it calls LoadSkill with the skill name
5. The full SKILL.md content (and skill folder path) is returned to the agent

Writing High-Quality Skills

A well-crafted skill transforms a general-purpose agent into a specialized one. Follow these principles to maximize effectiveness.

SKILL.md Structure

Every SKILL.md must start with YAML frontmatter containing name and description:

---
name: my-skill
description: Brief description of what this skill does. This skill should be used when [trigger conditions].
---

# Skill Title

[Purpose — what this skill provides, in 1-2 sentences]

## When to Use

[Concrete trigger conditions — when should the agent load this skill]

## Workflow / Instructions

[Step-by-step procedural knowledge]

## Bundled Resources

[Table of scripts, references, and assets with their purposes]

Metadata Quality

The name and description in the frontmatter determine when the agent will load the skill. Write them carefully:

• name: Use lowercase kebab-case (my-skill, not MySkill or my_skill)
• description: Be specific about what the skill does and when to use it. Use third-person form (e.g., "This skill should be used when..." instead of "Use this skill when...")

Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) — Always in the agent's system prompt (~100 words)
2. SKILL.md body — Loaded when the agent calls LoadSkill (target: <5k words)
3. Bundled resources — Loaded on demand as the agent reads specific files (unlimited)

Keep SKILL.md lean by moving detailed reference material to references/ files. Only include essential procedural instructions and workflow guidance in the main body.

Writing Style

• Use imperative/infinitive form (verb-first instructions), not second person
• Write "To accomplish X, do Y" rather than "You should do X"
• Keep instructions actionable and specific — vague steps produce vague behavior
• Reference bundled resources explicitly so the agent knows they exist and when to use them

Bundled Resources Guidelines

| Type | Directory | When to Include | Example | |------|-----------|-----------------|---------| | Scripts | scripts/ | Same code is rewritten repeatedly or deterministic reliability is needed | scripts/validate_config.py | | References | references/ | Documentation the agent should consult while working | references/api_schema.md | | Assets | assets/ | Files used in the output (templates, images, boilerplate) | assets/templates/starter.yaml |

Avoid duplication: Information should live in either SKILL.md or reference files, not both. For large reference files (>10k words), include grep search patterns in SKILL.md to help the agent locate relevant sections.

Choosing Between Skill Types

| Criteria | Folder-Based | Tool-Based | |----------|-------------|------------| | Needs extensive documentation | ✓ | | | Includes multiple files (scripts, templates) | ✓ | | | Single, well-defined capability | | ✓ | | Tool description is sufficient documentation | | ✓ | | Will be shared across projects | ✓ | |

Common Pitfalls

• Putting too much detail in SKILL.md instead of references/ — bloats context on every load
• Vague frontmatter description — the agent cannot determine when to use the skill
• Missing resource references — the agent does not know bundled files exist unless told
• Absolute paths in documentation — use relative paths within the skill folder
• Duplicating information between SKILL.md and reference files