agents-best-practices

Agents Best Practices

Use this skill when the user asks how to build, improve, debug, or evaluate an agentic harness. This is a general-purpose agent architecture skill. Coding agents are one subdomain only; apply the same principles to research, finance, legal, support, operations, sales, healthcare, education, data analysis, procurement, and workflow automation agents.

Core stance

An agent harness is the control plane around a model. The model proposes actions; the harness validates, authorizes, executes, records, summarizes, and returns observations. Keep the loop simple and make the runtime rigorous.

Default architecture:

user/task
  -> instruction and context builder
  -> model call
  -> tool/action proposal
  -> schema validation
  -> permission decision
  -> execution or approval pause
  -> structured observation
  -> context update
  -> repeat within budget or finish

Completion and reconciliation

For an action request, treat a discovered problem as a state transition, not a terminal report. Before calling the request complete, reconcile every required item using the contract in completion-reconciliation.md. Diagnosis-only internal gaps re-enter owned work; final prose is never a completion signal.

When to activate this skill

Use this skill for prompts involving any of these intents:

• build an agent, agentic workflow, AI worker, autonomous assistant, or harness;
• create a domain-specific MVP agent design, starter harness, implementation blueprint, or first production-safe version;
• choose between OpenAI, Anthropic, OpenAI-compatible APIs, direct tool loops, hosted tools, or SDKs;
• design tools, permissions, guardrails, approval flows, or sandboxing;
• design an agent for a partially known or changing environment using capability discovery, safe probing, runtime binding, schema verification, or drift invalidation;
• reduce code-mode or programmatic-tool latency through speculative execution, partial-program analysis, futures, exact claim semantics, or cancellation of unused work;
• create planning mode, workflow orchestration, goal mode, todo tracking, or long-running task behavior;
• add context compaction, memory, retrieval, scoped instructions, or prompt hierarchies;
• design a recursive language model (RLM), programmable-context runtime, self-refining or continual harness, retained child agents, daemon-backed or scheduled agent, or executable skills;
• attach Agent Skills, reusable workflows, MCP servers, external connectors, or tool search;
• audit an existing agent for reliability, cost, prompt-cache hit rate, safety, latency, or observability;
• create system prompts or developer instructions for a domain-specific agent;
• make source-of-truth knowledge, validation signals, logs, metrics, or workflow state legible to an agent.