local-agent-builder

name	local-agent-builder
description	Complete blueprint, constraints, and scaffolding for building agentic workflows optimized for local LLMs.

Local LLM Agent Development Guide

You are instructed to build agentic workflows specifically optimized for Local LLMs (e.g., Qwen 3.5, Gemma-4). Your primary objective is strict context management, low memory bandwidth utilization, and robust parsing of LLM outputs on constrained hardware.

You MUST use Microsoft's agent-framework to implement these tasks.

You must rigorously adhere to the blueprints mapped out in the resources/docs/ directory.

Required Blueprints

Familiarize yourself with and deploy the exact recipes documented below.

You will find the scaffold project and documentation for how to create agents in the examples and resources subfolders of this skill. DO NOT edit or touch the files inside these folders. These are strictly read-only references for you.

MANDATORY CHECKLIST: Before presenting any implementation_plan.md or completing your final code generation, you MUST explicitly evaluate your work against CHECKLIST.md — TWICE:

1. First pass (after writing implementation_plan.md): Verify structural correctness — scaffold integrity (§1), sub-agent delegation (§2), tool quotas (§3), and optional extensions (§4).
2. Second pass (after writing final code): Verify data-flow integrity — agent-ID routing in prompts, filename propagation between parent/child agents, and tool consistency with the delegation model (§5: Multi-Tier Data Flow Validation).

CRITICAL PATH RESOLUTION FOR AI AGENTS: Since this skill may be loaded from a global skills directory (e.g., ~/opencode/skills/) or local skills directory (e.g., .opencode/skills/), all file paths mentioned below (like resources/... and examples/...) are relative to the folder containing this SKILL.md file. You MUST resolve these to their absolute paths using SKILL.md's location before using your tools to list, read, or copy them. Do not assume they are in the current working directory.

[!TIP] CONTEXT MANAGEMENT: AVOID READING ALL DOCS AT ONCE. Your context window is limited! Do not blindly read every .md document in the resources/docs/ folder. Usually, you only need to read ARCHITECTURE.md and IMPLEMENTATION.md and possibly TOOLS.md. Skip documents like SHELL.md or MAILBOX.md unless the user explicitly requests those specific advanced capabilities.

MANDATORY STARTING STEPS FOR BUILDING NEW APPLICATIONS:

• STAGE 1 (Baseline Scaffold): First, you MUST copy the entire contents of the examples/basic-tui-agent/ directory to the current project directory as your primary starting point, and read its README.md. Never start from scratch or build a custom directory structure.
  • Always rely on pyproject.toml for adding new dependencies. Do not create a requirements.txt file.
  • Modify the name field in the [project] block of the copied pyproject.toml to reflect the agent you are building (e.g., name = "local-research-agent").
  • Modify the [project.scripts] block in the copied pyproject.toml to name the system-wide executable command after the agent you are building (e.g. local-research-agent = "src.app:cli_main").
  • Instruct the user to install the agent using pipx install . in the final README.md.
• STAGE 2 (Optional Extensions): ONLY if the user explicitly requests email, background execution, or Mailbox responder features, you must instruct the user to install the global sasori daemon (pipx install ./packages/sasori). Do NOT write from-scratch polling logic. Instead, write an [agent_name]_plugin.py file inheriting from sasori.handler.BaseMailboxHandler, and instruct the user to place it in their ~/.sasori/handlers/ directory. Remind the user they'll need to restart the sasori daemon.

[!CAUTION] STRICT REUSE DIRECTIVE: DO NOT REWRITE FROM SCRATCH OR INVENT PATTERNS. You are explicitly forbidden from rewriting the core scaffold architecture. Your task is to perform LIGHT MODIFICATIONS to the provided basic-tui-agent files.

• Always start by copying the basic scaffold to the current project directory. Do not write new orchestrators or custom setup files from scratch.
• Modify as little as possible of the scaffold—it works like a charm! The baseline loop, TUI system, and orchestration engine are robust and ready out-of-the-box. Avoid unnecessary refactoring or "improvement" of the existing code.
• DO NOT rewrite existing tools from scratch: Assume that if a tool exists in the scaffold (e.g., in src/tools/), it does not require editing or only requires minor edits. Review the tool implementation and associated docs to see if it can just be used without modification, and prioritize that. If you are rewriting an entire tool that already exists, you are likely getting it wrong. Keep modifications to the absolute minimum. If modification is needed, check existing docs, guidelines, and source comments for hints on how to modify it, rather than inventing your own logic.
• Preserve required engine imports/variables: The core engine (src/engine/) imports specific variables and constants from customization files (such as ORCHESTRATOR_INSTRUCTIONS, SUBAGENT_INSTRUCTIONS, and SUBAGENT_DELEGATION_INSTRUCTIONS from src/prompts.py). NEVER rename, delete, or modify these variables directly without keeping the original variable names as aliases (e.g., SUBAGENT_INSTRUCTIONS = SEARCH_SUBAGENT_INSTRUCTIONS). Doing so causes fatal ImportError crashes at startup.
• NEVER pre-format prompts in src/app.py: Do not call .format() on system prompt strings (such as ORCHESTRATOR_INSTRUCTIONS or SUBAGENT_INSTRUCTIONS) inside src/app.py. Pass raw, unformatted strings to the AgentBuilder and SubAgentConfig constructors; the orchestration engine formats runtime placeholders (like {date} or {task_name}) dynamically. Pre-formatting them at startup will throw a KeyError because runtime variables are not yet available at startup.
• Focus edits strictly on customization files (mainly src/app.py and src/prompts.py): The primary aim of this skill is to translate the user-requested agent and subagent structure into src/app.py and src/prompts.py, and update the related README.md, pyproject.toml, and config YAML (src/config_template.yaml). MOST of your edits should be contained within these specific files to configure the required agent and subagent structure.
• One prompt per sub-agent type in prompts.py (CRITICAL): When the user requests multiple sub-agent types (e.g. Searcher + Analyzer), you MUST create a separate prompt constant for each one (e.g., SEARCH_SUBAGENT_INSTRUCTIONS, ANALYZER_SUBAGENT_INSTRUCTIONS). Do NOT reuse a single generic SUBAGENT_INSTRUCTIONS for all sub-agent types. Do NOT try to be clever by sharing, conditionally formatting, or composing a shared prompt across roles. Each sub-agent type gets its own fully self-contained prompt. Keep SUBAGENT_INSTRUCTIONS as a backward-compatibility alias pointing to one of them.
• Selective tool lists per sub-agent in app.py (CRITICAL): Each SubAgentConfig MUST have a selective tool list. Import individual tools from tools and pass only the ones that sub-agent needs. Do NOT assign WORKSPACE_TOOLS to every agent. Tool separation is what FORCES delegation — if a parent agent has the tools its child is supposed to use, the LLM will use them directly and never delegate. See ARCHITECTURE.md §2 for the exact code pattern.
• Minimize tool edits: While you might occasionally need to edit a tool's implementation, this should be minimal—mostly config adjustments or swapping specific code snippets as guided by docs and comment hints. Full rewrites of existing tool code are not recommended and will break the application.
• Avoid editing the core engine unless absolutely necessary: The src/engine/ directory handles all the complex Textual TUI and background thread orchestration. In 99% of cases you should NOT need to modify it — look for config toggles (config_template.yaml), format variables, or SDK parameters first. Only make minimal, targeted edits to engine files when there is genuinely no config-driven or SDK-level alternative.
• Never invent or hallucinate architectures. If a feature is needed, the required pattern is almost certainly already established inside the resources/docs/ documents or as exemplary code within the scaffold.
• Read the code, mimic its native structural patterns exactly, and only inject the specific business logic the user requested.

1. Architecture: Rules for context management and Flat vs Sub-Agent pipelines. (CRITICAL: Configure sub-agents via the AgentBuilder SDK inside src/app.py! The orchestration engine already natively supports nested sub-agent delegation out-of-the-box. NEVER edit src/engine/orchestrator.py to add delegation support or custom format variables. Each SubAgentConfig declares its own children via sub_agents=[...] to form a scoped delegation chain — the engine only injects delegate_tasks into agents that have children, and each agent can only see its own declared children. The engine auto-populates prompt format variables for ALL agents (orchestrator + sub-agents): {date}, {workspace_dir}, {task_name} (sub-agents only), {delegation_instructions}, and all quota keys as {tool_name_quota} from config. The engine uses a safe formatter — unknown keys stay as literal text instead of crashing.)
2. Implementation: Vital Python boilerplates for <think> tag scraping, TUI integrations, and Headless CLI (--prompt, --auto-approve, --resume) batch processing. Includes rules on deleting (pruning) optional features like markitdown parsers or web_search to save context if unneeded.
3. Tools: Copy-paste snippets for Web Search, Parsing, Virtual FS, and Shell Execution. (Note: The shell tool introduces monumental security risks. You must explicitly remove run_shell_command from the scaffold if unused, unless the user specifically demands bash or compilation capabilities!)
4. UI Guidelines: Textual rendering rules, spanning the OptionList dropdown components and the collapsible workspace file viewers natively triggered via /files commands (dynamically reads from in-memory or on-disk based on config.yaml).
5. Coding Guidelines: LLM-focused code quality constraints (e.g. flat directory layouts over nesting, strict type hints, and eliminating useless inline comments to preserve tokens).
6. Prompting & Delegation Guidelines: Architectural rules for structuring Microsoft Agent-Framework pipelines. (CRITICAL: The scaffold's system prompts in src/prompts.py are pre-optimized templates. You must retain all formatting variables like {task_name} or {date} in custom instructions. If you strip {task_name}, sub-agents run blindly. Ensure the orchestrator's instructions explicitly command it to analyze the user query, break it down into specific tasks, and propagate them to the sub-agents!)
7. Mailbox Daemon Pattern: Architectural rules for wrapping agents into an optional background email workflow.
8. RAG & Vector Search: Architecture and tools for building Retrieval-Augmented Generation agents with local vector search (sqlite-vec). Only read this if the user requests document corpus querying, semantic search, or RAG capabilities.
9. Evaluation Framework: How to build an eval/ harness for any agent you create. The scaffold ships with a generic evaluate.py and eval_config.yaml template in examples/basic-tui-agent/eval/. Agents are scored by running them headlessly and checking their output (stdout or a named workspace artifact) against criteria using one of three strategies: contains, regex, or llm_judge. Only read this if the user asks for evaluation or benchmarking of the built agent.

Internal & External References

You should search through and read the official Microsoft agent-framework documentation and samples before guessing APIs or mechanisms:

Agent Framework Examples (Search inside these web URLs or even pull the entire github repo is you need to have stuff locally that you can inspect):

• Core Agent Patterns: Inspect https://github.com/microsoft/agent-framework/tree/main/python/samples/02-agents/
• DAG Workflow Patterns: Inspect https://github.com/microsoft/agent-framework/tree/main/python/samples/03-workflows/ (specifically checkpoint/ and control-flow/ examples)

External Web Documentation:

• Microsoft agent-framework: Documentation | GitHub Repository
• Textual (UI Framework): Documentation
• Document Extractors: MarkItDown | LlamaIndex Liteparse