Context

NexAU is an AI agent framework providing tools, middleware, config loading, and an execution loop. An Evolution Agent modifies a NexAU coding agent by creating/editing middleware, tools, skills, sub-agents, and config files.

The Evolution Agent has NO pre-existing NexAU framework knowledge. Your output will be its sole reference. Focus on:

1. How to write middleware — base class, hook methods, params, registration, real examples from source
2. How to create tools — YAML schema, Python function signature, binding, agent_state injection
3. How to create skills — SKILL.md format, frontmatter, registration, loading mechanism
4. How to create sub-agents — config schema, registration, invocation, context isolation
5. YAML config schema — complete field reference with types, defaults, required/optional
6. Key runtime behaviors — only what's needed to write correct components (hook order, error handling, tool execution)

Source Code Location (READ ONLY)

• NexAU framework: {{ nexau_path }}

Output Directory (WRITE)

• Skill file: {{ output_skill_dir }}/nexau-framework-internals/SKILL.md

⚠️ MANDATORY WORKFLOW: Explore-Write-Refine Cycles

You MUST follow this phased workflow. Do NOT spend all your time reading.

Phase 1: Scan & Scaffold (iterations 1-15)

1. list_directory and glob to map the codebase structure
2. Read key files: config dataclasses, hooks.py base class, existing middleware/tool implementations
3. WRITE the initial SKILL.md with whatever you have — even if incomplete, use "[TODO]" placeholders

Phase 2: Practical Patterns (iterations 16-60)

4. For each section below, find real code examples from the source
5. After each section, immediately write_file to UPDATE SKILL.md
6. Priority order: §1 Config → §2 Middleware → §3 Tools → §4 Skills → §5 Sub-Agents → §6 Runtime

Phase 3: Polish & Complete (iterations 61-80)

7. Fill remaining "[TODO]" sections, add copy-paste templates
8. Call complete_task

HARD RULES:

• You MUST call write_file for SKILL.md before iteration 20. No exceptions.
• You MUST call write_file to update SKILL.md at least every 15 iterations after that.
• If you reach iteration 100 without having called write_file, you have FAILED.
• Use read_file with offset/limit for large files.
• Cite file:line_range for every claim. Include actual code snippets.

Exploration Guide — What to Extract

For each section, find the real implementation in source code and extract patterns the Evolution Agent can copy.

§1. YAML Config Schema (HIGHEST PRIORITY)

Find the config dataclass definitions in nexau/archs/main_sub/config/. Document:

• All top-level fields in agent.yaml: type, name, system_prompt, system_prompt_type, tool_call_mode, llm_config, max_iterations, max_context_tokens, sandbox_config, tools, middlewares, skills, sub_agents, stop_tools, tracers — with types, defaults, required/optional
• llm_config sub-fields: model, base_url, api_key, max_tokens, temperature, stream, api_type, reasoning, etc.
• tools: entry format: name, yaml_path, binding — how each is resolved
• middlewares: entry format: import, params — how the import string is resolved, what's added to sys.path
• skills: entry format: path format, how skills are discovered and loaded
• sub_agents: entry format: name, config_path, description — how config_path is resolved
• ${env.XXX} resolution: behavior when env var is not set
• Relative path resolution: relative to what? (YAML file directory? CWD? work_dir?)

§2. Middleware Creation (HIGHEST PRIORITY)

Find the middleware base class and several existing middleware implementations. Extract:

2.1 Base Class & Hook Methods

• What class to inherit from? Find the exact import path and class name.
• ALL available hook methods with their EXACT signatures (parameter names, types, return type):
  • before_model(input) -> HookResult
  • after_model(input) -> HookResult
  • before_tool(input) -> HookResult
  • after_tool(input) -> HookResult
  • wrap_model_call(...) — how to wrap the LLM call
  • wrap_tool_call(...) — how to wrap tool execution
  • Any others (before_agent, after_agent, etc.)
• HookResult: What can it modify? How to inject messages? How to modify tool output? Show the class definition.
• Hook input types: What fields are available in BeforeModelHookInput, AfterModelHookInput, BeforeToolHookInput, AfterToolHookInput?

2.2 How Params Are Passed

• How does params: in YAML map to __init__ arguments? Find the exact code.
• Can middleware access agent_state? How?

2.3 Registration

• How does import: middleware.my_module:MyClass get resolved? What directory is added to sys.path?
• Ordering: do middlewares execute in YAML order? What about after_* hooks?

2.4 Real Examples

Find 2-3 existing middleware implementations in the source and extract their patterns:

• A simple one (e.g., output truncation)
• A complex one (e.g., context compaction) Show the class structure, how params are received, how hooks are implemented.

2.5 Copy-Paste Template

Based on what you found, provide a minimal middleware template that the Evolution Agent can copy.

§3. Tool Creation (HIGH PRIORITY)

3.1 Tool YAML Schema

Find a tool YAML definition (e.g., read_file.tool.yaml). Document the full schema:

• name, description, input_schema (JSON Schema format), etc.

3.2 Python Function Signature

• How does binding: tools.my_module:my_func resolve to a Python function?
• How is agent_state injected? Is it based on inspect.signature? What fields does agent_state have (sandbox, history, etc.)?
• What should the function return? How are return values normalized?
• What happens if the tool raises an exception?

3.3 Registration

• The tools: list entry format in agent YAML
• How yaml_path and binding are resolved (relative to config dir? work_dir?)

3.4 Real Examples

Find 2-3 existing tool implementations. Show the function signature, how sandbox is used, return format.

3.5 Copy-Paste Template

Provide a minimal tool template (YAML + Python).

§4. Skill System (MEDIUM PRIORITY)

• SKILL.md format: What frontmatter fields are expected (name, description, etc.)?
• How skills are loaded: What triggers LoadSkill? How does the agent decide which skill to load?
• skills: in agent YAML: path format (relative to what?), how directories are scanned
• Skill content: How is SKILL.md content injected into the conversation? As a user message? System message?

§5. Sub-Agent Creation (MEDIUM PRIORITY)

5.1 Config

• sub_agents: list entry format: name, config_path, description, etc.
• Sub-agent's own agent.yaml structure — does it inherit from parent? What's independent?
• How config_path is resolved

5.2 Runtime

• How sub-agent-{name}(message="...") is dispatched
• Context isolation: does sub-agent share history with parent?
• Return value: how result flows back to parent
• Does sub-agent get its own sandbox?

5.3 RecallSubAgent

• What does it do? When is it useful?

§6. Key Runtime Behaviors (LOWER PRIORITY — only what affects component writing)

Only document behaviors that affect how middleware/tools should be written:

• Hook execution order: before_* top-to-bottom or bottom-to-top? after_* order?
• Tool error handling: What happens when a tool throws? What message does the LLM see?
• Parallel tool execution: Are multiple tool calls run in parallel? What controls this?
• Stop tool behavior: When complete_task is called, do after_tool hooks still fire?
• Context compaction: When does it trigger? What gets compacted? (needed for designing middleware that interacts with compaction)
• Token counting: What function/heuristic is used? (needed for middleware that checks token budget)

§7. Gotchas & Common Mistakes

Look for anything that would trip up the Evolution Agent:

• Config errors that pass validation but crash at runtime
• Middleware hooks that don't fire when expected
• Tool binding resolution surprises
• Sub-agent gotchas (sandbox sharing, nested depth limits)
• Import path resolution edge cases

Skill Deliverable Format

---
name: nexau-framework-internals
description: >-
  NexAU framework practical development guide. How to create middleware,
  tools, skills, and sub-agents. Complete YAML config reference.
  Key runtime behaviors and gotchas. Auto-generated from source code.
---

# NexAU Framework — Practical Development Guide

> Source: `{{ nexau_path }}`. Each claim cites `file:line_range`.

## §1. YAML Config Schema

### 1.1 Full Field Reference
| Field | Type | Default | Required | Notes |
|-------|------|---------|----------|-------|
| type | str | - | yes | Always "agent" |
| ... | ... | ... | ... | ... |

### 1.2 llm_config Fields
...

### 1.3 Path Resolution Rules
...

## §2. Middleware — How to Write

### 2.1 Base Class & Hook Methods
**Import**: `from nexau.archs.main_sub.execution.hooks import Middleware, HookResult, ...`

**Available hooks** (all optional):
| Hook | Fires when | Input type | Can modify |
|------|-----------|------------|-----------|
| before_model | Before LLM call | BeforeModelHookInput | messages |
| ... | ... | ... | ... |

### 2.2 Minimal Template
```python
from nexau.archs.main_sub.execution.hooks import (
    AfterToolHookInput, HookResult, Middleware
)

class MyMiddleware(Middleware):
    def __init__(self, my_param: int = 10, **kwargs):
        super().__init__(**kwargs)
        self.my_param = my_param

    async def after_tool(self, input: AfterToolHookInput) -> HookResult:
        # input.tool_name, input.tool_output, input.messages, ...
        return HookResult.with_modifications(tool_output=modified_output)

2.3 Registration in YAML

middlewares:
  - import: middleware.my_module:MyMiddleware
    params:
      my_param: 42

2.4 Real Examples from Source

[extracted from actual middleware implementations]

§3. Tools — How to Create

[similar structure: template, YAML schema, real examples]

§4. Skills — How to Create

[format, registration, loading]

§5. Sub-Agents — How to Create

[config, registration, invocation, context isolation]

§6. Key Runtime Behaviors

[only what affects component development]

§7. Gotchas & Common Mistakes

Gotcha	Source	Impact
...	file:line	...

# Quality Criteria

The skill file MUST:
1. Provide **copy-paste ready templates** for creating middleware, tools, skills, sub-agents
2. Include **real code examples** extracted from existing framework implementations
3. Cite `file:line_range` for every claim
4. Prioritize **practical "how to"** over theoretical internals
5. Be 400-800 lines — comprehensive but focused on what the Evolution Agent actually needs

When done, call `complete_task`.