agents-best-practices-harness-design

# agents-best-practices Skill > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. This skill provides **provider-neutral best practices** for designing, auditing, and refactoring **agentic harnesses**—the control plane around a model that validates, authorizes, executes, and observes tool calls. It applies to coding agents, research agents, support, operations, finance, legal, healthcare, education, and workflow automation agents. **Core principle**: *The model proposes actions; the harness validates, authorizes, executes, records, and returns observations.* --- ## What This Skill Does - **Generate MVP agent blueprints** for new domains with typed tools, permissions, and launch gates - **Audit existing agent harnesses** for brittle loops, unbounded tools, missing budgets, and observability gaps - **Design tools and permissions** with risk-appropriate approval gates - **Structure planning mode** and goal-like loops with checkpoints and budgets - **Build context and memory strategies** that preserve active state across compaction - **Optimize prompt caching** and cost telemetry - **Integrate skills, MCP, and external connectors** with progressive disclosure - **Implement security, evals, and observability** for production readiness --- ## Installation ### Option A: Via `skills` CLI (Recommended) ```bash npx skills add DenisSergeevitch/agents-best-practices -g ``` The `-g` flag installs globally for all projects. ### Option B: Manual Install **For Codex:** ```bash mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" git clone https://github.com/DenisSergeevitch/agents-best-practices.git \ "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices" ``` **For Claude Code (user-level):** ```bash mkdir -p "$HOME/.claude/skills" git clone https://github.com/DenisSergeevitch/agents-best-practices.git \ "$HOME/.claude/skills/agents-best-practices" ``` **For Claude Code (project-level):** ```bash mkdir -p .claude/skills git clone https://github.com/DenisSergeevitch/agents-best-practices.git \ .claude/skills/agents-best-practices ``` ### Verification After install, verify the skill is discoverable: ```bash # Codex ls "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices" # Claude Code ls "$HOME/.claude/skills/agents-best-practices" ``` You should see `SKILL.md`, `README.md`, `icon.jpeg`, and `references/`. --- ## Repository Structure ``` agents-best-practices/ ├── SKILL.md # skill entrypoint (this file) ├── README.md # public-facing overview ├── icon.jpeg # skill icon └── references/ ├── mvp-agent-blueprint.md # MVP harness generator ├── architecture.md # component model ├── agentic-loop.md # loop invariants and budgets ├── tools-and-permissions.md # typed tools and risk classes ├── planning-and-goals.md # planning mode and long-running goals ├── context-memory-compaction.md # context, memory, retrieval ├── prompt-caching-and-cost.md # cache-aware context layout ├── skills-and-connectors.md # Agent Skills, MCP, connectors ├── system-prompts-instructions.md # instruction hierarchy ├── provider-api-patterns.md # OpenAI, Anthropic, compatible APIs ├── security-evals-observability.md # guardrails, tracing, evals ├── agent-legibility-feedback-loops.md # artifacts and cleanup ├── checklists.md # implementation and audit checklists ├── coverage-audit.md # topic coverage verification └── source-links.md # official references ``` --- ## Core Concepts ### 1. The Agentic Loop Every agent follows this pattern: ``` user/task → context builder → model call → typed tool call → schema validation → permission check → execution or pause → structured observation → next step or final answer ``` **Key invariants:** - Every tool call gets a result (success, denial, timeout, malformed, abort) - Risk changes the loop (reads vs. drafts vs. writes vs. external communications) - Budgets prevent runaway loops (steps, time, tokens, cost, tool calls) - Active state survives compaction Reference: `references/agentic-loop.md` ### 2. Tools and Permissions **Risk classes** determine permission requirements: | Risk Class | Examples | Permission | |------------|----------|------------| | `read_private_data` | Read CRM, support tickets | Autonomous with scope | | `draft_external_message` | Draft email, Slack message | Autonomous with label | | `write_database` | Update record | Approval gate | | `external_communication` | Send email, post to Slack | Approval gate | | `destructive_action` | Delete, archive | Approval gate | | `privileged_access` | Admin tools, deploy | Approval gate | | `financial_operation` | Charge card, transfer funds | Approval gate | **Pattern: Typed Tools** ```typescript // Good: Narrow, typed, deterministic interface SendCustomerEmailTool { name: "send_customer_email"; parameters: { account_id: string; template: "renewal_reminder" | "upgrade_offer" | "support_followup"; variables: Record<string, string>; }; permission: "approval_gate"; } // Bad: Generic, untyped, unbounded interface SendMessageTool { name: "send_message"; parameters: { to: string; body: string; }; } ``` Reference: `references/tools-and-permissions.md` ### 3. Planning and Goals **Planning mode** separates thinking from acting: ```typescript interface PlanningResult { plan: string; // What the agent intends to do required_approvals: string[]; // Tools needing human approval estimated_steps: number; estimated_cost_usd: number; risk_summary: string; } // User approves the plan, then agent executes ``` **Goal-like loops** need: - Step budget (e.g., max 20 steps) - Time budget (e.g., 5 minutes) - Cost budget (e.g., $0.50) - Checkpoints (e.g., save state every 5 steps) - Termination reasons (success, budget, validation failure, user abort) Reference: `references/planning-and-goals.md` ### 4. Context and Memory **Context hierarchy:** ```typescript interface AgentContext { // Stable, cache-friendly prefix system_instructions: string; skill_descriptions: string[]; // Active state (outside prompt) plan: Plan | null; pending_approvals: Approval[]; todos: Todo[]; artifacts: Artifact[]; // Recent conversation (compacted) messages: Message[]; // Retrieved knowledge retrieved_docs: Document[]; } ``` **Compaction rules:** 1. Preserve active state (plan, approvals, todos, artifacts) outside the prompt 2. Summarize conversation, not decisions 3. Rehydrate from state, not chat history 4. Label trust boundaries (user, model, tool, external) Reference: `references/context-memory-compaction.md` ### 5. Prompt Caching **Cache-aware layout:** ```typescript // Stable prefix (cached) const systemPrefix = [ systemInstructions, allSkillDescriptions, allToolSchemas, permanentExamples ]; // Dynamic suffix (not cached) const dynamicSuffix = [ retrievedDocs, recentMessages, currentTask ]; // OpenAI: system, cached_user, user // Anthropic: system (cached), user (cached), user ``` **Cost telemetry:** ```typescript interface ModelCallTelemetry { input_tokens: number; output_tokens: number; cached_tokens: number; cost_usd: number; cache_hit_rate: number; } ``` Reference: `references/prompt-caching-and-cost.md` ### 6. Skills and Connectors **Progressive disclosure:** ```typescript // Step 1: Load skill summaries (cached) const skillIndex = [ { name: "web-search", description: "Search the web..." }, { name: "code-analysis", description: "Analyze codebases..." } ]; // Step 2: Load full skill when relevant if (userNeedsWebSearch) { const webSearchSkill = loadSkill("web-search"); context.push(webSearchSkill.fullInstructions); } ``` **MCP integration:** ```typescript // Expose MCP server as typed tools const mcpTools = await mcpClient.listTools(); for (const tool of mcpTools) { registerTool({ name: tool.name, description: tool.description, parameters: tool.inputSchema, permission: classifyRisk(tool.name) }); } ``` Reference: `references/skills-and-connectors.md` --- ## Common Patterns ### Pattern 1: Generate MVP Agent Blueprint **User request:** ``` Build an agent for account renewal risk. It should read CRM, support tickets, and usage data, then draft renewal actions. ``` **Agent response using this skill:** ```markdown ## MVP Blueprint: Account Renewal Risk Agent **Harness level:** Approval-gated Level 2 **Core loop:** user/task → context builder → model call → typed tool call → schema validation → permission check → execution or pause → structured observation → next step or final brief **Minimal tools:** 1. `read_account_profile` - permission: `read_private_data` - Input: account_id - Output: { name, tier, arr, contract_end_date, renewal_probability } 2. `list_support_tickets` - permission: `read_private_data` - Input: account_id, days: 90 - Output: Ticket[] 3. `fetch_usage_summary` - permission: `read_private_data` - Input: account_id, days: 30 - Output: { active_users, feature_adoption, last_login } 4. `draft_customer_email` - permission: `draft_external_message` - Input: account_id, template, variables - Output: { subject, body, draft_id } 5. `request_approval` - permission: `approval_gate` - Input: action, rationale, draft_id - Output: { approval_id, status: "pending" } **Launch gate:** - 20 historical accounts processed - Trace review confirms no unapproved external sends - Human acceptance on ≥80% of draft actions - No unbounded tool results or timeout loops **Implementation checklist:** - [ ] Typed tools with JSON schemas - [ ] Permission check before every execution - [ ] Step budget (max 15 steps per account) - [ ] Cost telemetry and budget ($0.10 per account) - [ ] Structured observations with trust labels - [ ] Eval: injection, timeout, missing result, budget exhaustion ``` Reference: `references/mvp-agent-blueprint.md` --- ### Pattern 2: Audit Existing Agent **User request:** ``` Our research agent sometimes runs tools forever and forgets why it made a decision after context compaction. Audit the harness. ``` **Agent response using this skill:** ```markdown ## Audit: Research Agent Harness **Failure points identified:** 1. **No loop budgets** (agentic-loop.md) - Missing: step budget, time budget, cost budget - Risk: Runaway loops, cost overruns - Fix: Add `max_steps: 30`, `timeout_seconds: 300`, `max_cost_usd: 2.0` 2. **Compaction loses active state** (context-memory-compaction.md) - Current: Summarizes chat history, drops plan and approvals - Risk: Agent forgets what it's doing mid-task - Fix: Store plan, approvals, todos, artifacts outside prompt; rehydrate on load 3. **Tool results unbounded** (tools-and-permissions.md) - Current: Returns full API responses (some 50KB+) - Risk: Context overflow, cost explosion - Fix: Add `max_result_bytes: 4096` and structured summarization 4. **No event trace** (security-evals-observability.md) - Current: Logs model input/output only - Risk: Cannot debug tool call → execution → observation flow - Fix: Add structured trace: `{ step, tool, args, result, duration, cost }` 5. **Trust boundaries unlabeled** (context-memory-compaction.md) - Current: Mixes user input, model output, tool results - Risk: Injection attacks, confused deputy - Fix: Label every message: `source: "user" | "model" | "tool" | "external"` **Fix priority:** 1. Add loop budgets and termination reasons 2. Move active state outside prompt 3. Bound tool results and add structured observations 4. Add event trace 5. Add evals for injection, timeout, budget exhaustion ``` References: `references/agentic-loop.md`, `references/context-memory-compaction.md`, `references/security-evals-observability.md` --- ### Pattern 3: Design Tools and Permissions **User request:** ``` The ops agent needs Slack, Linear, Google Drive, and our internal deploy API. How should tools and permissions work? ``` **Agent response using this skill:** ```markdown ## Tool Design: Ops Agent **Risk classification:** | Tool | Risk Class | Permission | |------|------------|------------| | `search_linear_issues` | `read_private_data` | Autonomous (scoped) | | `read_gdrive_doc` | `read_private_data` | Autonomous (scoped) |