ai-agent-builder

# AI Agent Builder Skill — Agentic System Design ## Identity You architect AI agents that reliably produce professional-quality outputs. You understand that the gap between a "chatbot wrapper" and a real agent is: structured tool use, skill-based prompting, iterative execution, and quality gates. --- ## CORE PRINCIPLE > **An agent is a loop, not a call.** > Single LLM call = chatbot. LLM + tools + iteration + validation = agent. ``` ┌─────────────────────────────────────────┐ │ AGENT EXECUTION LOOP │ │ │ │ Plan → Execute → Observe → Validate │ │ ↑ │ │ │ └───── Fix if invalid ──────┘ │ │ │ │ Stop when: success OR max_retries │ └─────────────────────────────────────────┘ ``` --- ## ARCHITECTURE PATTERNS ### Pattern 1: Tool-Using Agent (Most Common) ``` User Request ↓ System Prompt + Skill Context ↓ LLM generates plan ↓ LLM calls tools (file_write, shell_exec, web_search, etc.) ↓ Tool results fed back to LLM ↓ LLM validates output ↓ Deliver or retry ``` **Best for:** Code generation, file manipulation, data analysis, research ### Pattern 2: Skill-Loaded Agent ``` User Request → Classify task type → Load relevant skill(s) ↓ Inject skill into system prompt ↓ Execute with tool use ↓ Quality gate from skill checklist ``` **Best for:** Multi-domain agents (code + UI + docs + data) ### Pattern 3: Multi-Agent Pipeline ``` Agent 1: Planner → Decomposes task into subtasks Agent 2: Implementer → Executes each subtask with tools Agent 3: Reviewer → Reviews output, requests fixes Agent 4: Integrator → Combines outputs into final deliverable ``` **Best for:** Complex multi-file projects, but higher cost and latency. **Warning:** Start with single-agent + tools. Only add agents when single-agent fails. ### Pattern 4: ReAct (Reason + Act) ``` Thought: I need to find the user's API key location Action: search_files("*.env", "API_KEY") Observation: Found in .env line 3: CLAUDE_API_KEY=sk-... Thought: Now I need to read the config to see how it's loaded Action: read_file("config.py") Observation: Uses os.environ.get("CLAUDE_API_KEY") Thought: The key is loaded correctly. Now I can... ``` **Best for:** Complex reasoning tasks requiring multiple observations --- ## TOOL DESIGN ### Tool Design Principles ``` 1. ATOMIC: Each tool does ONE thing well 2. TYPED: Clear input/output schemas with descriptions 3. SAFE: Tools validate inputs and handle errors gracefully 4. OBSERVABLE: Tools return structured results the LLM can reason about 5. IDEMPOTENT: Safe to call multiple times with same input (where possible) ``` ### Essential Tool Set for a Coding Agent ```python TOOLS = [ { "name": "read_file", "description": "Read the contents of a file at the given path. Returns file content as string.", "input_schema": { "type": "object", "properties": { "path": {"type": "string", "description": "Absolute or relative file path"} }, "required": ["path"] } }, { "name": "write_file", "description": "Write content to a file. Creates the file if it doesn't exist, overwrites if it does.", "input_schema": { "type": "object", "properties": { "path": {"type": "string", "description": "File path to write to"}, "content": {"type": "string", "description": "Full file content to write"} }, "required": ["path", "content"] } }, { "name": "edit_file", "description": "Replace a specific string in a file. The old_str must appear exactly once.", "input_schema": { "type": "object", "properties": { "path": {"type": "string"}, "old_str": {"type": "string", "description": "Exact string to find (must be unique)"}, "new_str": {"type": "string", "description": "Replacement string"} }, "required": ["path", "old_str", "new_str"] } }, { "name": "run_command", "description": "Execute a shell command and return stdout/stderr. Use for running tests, linters, builds.", "input_schema": { "type": "object", "properties": { "command": {"type": "string", "description": "Shell command to execute"}, "timeout": {"type": "integer", "description": "Timeout in seconds (default 30)", "default": 30} }, "required": ["command"] } }, { "name": "search_files", "description": "Search for a pattern across files in a directory. Returns matching file paths and line numbers.", "input_schema": { "type": "object", "properties": { "pattern": {"type": "string", "description": "Regex or text pattern to search for"}, "directory": {"type": "string", "description": "Directory to search in", "default": "."}, "file_glob": {"type": "string", "description": "File glob pattern (e.g., '*.py')", "default": "*"} }, "required": ["pattern"] } }, { "name": "list_directory", "description": "List files and directories at the given path, up to 2 levels deep.", "input_schema": { "type": "object", "properties": { "path": {"type": "string", "description": "Directory path", "default": "."} } } } ] ``` ### Tool Implementation Pattern (Python) ```python import subprocess import os from pathlib import Path def execute_tool(name: str, input_data: dict) -> str: """Execute a tool and return result as string for the LLM.""" try: match name: case "read_file": path = Path(input_data["path"]) if not path.exists(): return f"ERROR: File not found: {path}" if path.stat().st_size > 100_000: return f"ERROR: File too large ({path.stat().st_size} bytes). Read specific sections." return path.read_text(encoding="utf-8") case "write_file": path = Path(input_data["path"]) path.parent.mkdir(parents=True, exist_ok=True) path.write_text(input_data["content"], encoding="utf-8") return f"SUCCESS: Wrote {len(input_data['content'])} chars to {path}" case "run_command": result = subprocess.run( input_data["command"], shell=True, capture_output=True, text=True, timeout=input_data.get("timeout", 30), cwd=os.getcwd() ) output = "" if result.stdout: output += f"STDOUT:\n{result.stdout[:5000]}\n" if result.stderr: output += f"STDERR:\n{result.stderr[:2000]}\n" output += f"EXIT CODE: {result.returncode}" return output case _: return f"ERROR: Unknown tool: {name}" except Exception as e: return f"ERROR: {type(e).__name__}: {str(e)}" ``` --- ## SKILL LOADING SYSTEM ### Skill File Structure ``` skills/ ├── frontend-ui/ │ └── SKILL.md # Design system, component patterns, animation rules ├── backend-api/ │ └── SKILL.md # REST design, error handling, auth patterns ├── database/ │ └── SKILL.md # Schema design, query optimization, migrations ├── testing/ │ └── SKILL.md # Test patterns, mocking, coverage targets ├── drawing/ │ └── SKILL.md # SVG, Canvas, p5.js, visualization patterns └── devops/ └── SKILL.md # Docker, CI/CD, deployment, monitoring ``` ### Skill Loader ```python from pathlib import Path from typing import Optional SKILL_DIR = Path("skills") SKILL_TRIGGERS = { "frontend-ui": ["ui", "component", "page", "layout", "design", "css", "react", "html", "dashboard", "landing"], "backend-api": ["api", "endpoint", "route", "server", "rest", "graphql", "middleware", "auth"], "database": ["database", "sql", "query", "schema", "migration", "model", "orm", "table"], "testing": ["test", "spec", "coverage", "mock", "assert", "tdd", "unit test", "integration test"], "drawing": ["draw", "svg", "canvas", "chart", "diagram", "visualize", "art", "graphic", "illustration"], "devops": ["deploy", "docker", "ci", "cd", "pipeline", "kubernetes", "monitor", "infrastructure"], } def detect_skills(user_message: str) -> list[str]: """Detect which skills to load based on the user's message.""" message_lower = user_message.lower() matched = [] for skill_name, triggers in SKILL_TRIGGERS.items(): if any(trigger in message_lower for trigger in triggers): matched.append(skill_name) return matched or ["backend-api"] # Default skill def load_skills(skill_names: list[str]) -> str: """Load and concatenate skill contents.""" contents = [] for name in skill_names: skill_path = SKILL_DIR / name / "SKILL.md" if skill_path.exists(): contents.append(f"# ACTIVE SKILL: {name}\n\n{skill_path.read_text()}") return "\n\n---\n\n".join(contents) ``` --- ## AGENT ORCHESTRATOR ### Full Agent Loop (Python + Claude API) ```python import anthropic from typing import Any client = anthropic.Anthropic() def run_agent( user_request: str, skills: list[str], tools: list[dict], max_iterations: int = 25 ) -> str: """Run the full agent loop until task completion or max iterations.""" skill_context = load_skills(skills) system_prompt = f"""You are an elite software engineer agent. {skill_context} ## Execution Rules 1. PLAN before coding. State your approach in 2-3 sentences. 2. Read existing code before modifying it. 3. Write complete, runnable code. Never use placeholders. 4. Run tests/linters after every change. 5. If tests fail, analyze the error and fix it. Retry up to 3 times. 6. When done, verify all requirements are met. ## Quality Gates Before marking as complete, verify: - All tests pass - No linter errors - All imports present - Edge cases handled - Code follows the loaded skill guidelines """ messages = [{"role": "user", "content": user_request}] for iteration in range(max_iterations): response = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=4096, system=system_prompt, tools=tools, messages=messages, ) # Check if agent is done (no more tool calls) if response.stop_reason == "end_turn": final_text = "".join( block.text for block in response.content if block.type == "text" ) return final_text # Process tool calls assistant_content = response.content messages.append({"role": "assistant", "content": assistant_content}) tool_results = [] for block in assistant_content: if block.type == "tool_use": result = execute_tool(block.name, block.input) tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": result }) messages.append({"role": "user", "content": tool_results}) return "ERROR: Agent exceeded maximum iterations without completing." ``` --- ## CONTEXT MANAGEMENT (Critical for Quality) ### Context Window Budget ``` TOTAL CONTEXT: ~200K tokens (Claude Sonnet) BUDGET ALLOCATION: System prompt + skills: 10-15K tokens (keep lean) Conversation history: 50-80K tokens Tool results: 50-80K tokens Working space for output: 20-30K tokens RULES: 1. Truncate old tool results after they're processed 2. Summarize conversation history every 10 turns 3. Keep skill files under 5K tokens each 4. Limit tool output to 5K chars per result 5. If context > 60% full, summarize and compress