agents-best-practices
"The model proposes actions; the harness validates, authorizes, executes, records, and returns observations."
A provider-neutral Agent Skill for designing, generating MVP blueprints for, auditing, refactoring, and explaining agentic harnesses.
It applies beyond coding agents: research, support, operations, sales, finance, data analysis, procurement, legal workflows, healthcare workflows, education, and workflow automation agents all need the same core runtime discipline.
Install - pick one:
A. With skills (any compatible agent):
npx skills add DenisSergeevitch/agents-best-practices -g
The -g flag installs globally at user level so every project can discover it.
B. Or paste this prompt to your AI agent:
Install the agents-best-practices skill for me:
1. Clone https://github.com/DenisSergeevitch/agents-best-practices into my
user-level skills directory as `agents-best-practices/`.
Use the skill directory my agent reads on this machine, for example:
- Codex: ~/.codex/skills/
- Claude Code: ~/.claude/skills/
2. Verify that SKILL.md, icon.jpeg, and the references/ directory are present.
3. Confirm the install path when done.
C. Manual install paths:
# Codex 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" # Claude Code, user-level mkdir -p "$HOME/.claude/skills" git clone https://github.com/DenisSergeevitch/agents-best-practices.git \ "$HOME/.claude/skills/agents-best-practices" # Claude Code, project-level mkdir -p .claude/skills git clone https://github.com/DenisSergeevitch/agents-best-practices.git \ .claude/skills/agents-best-practices
Keeping the skill current: On each new task, the skill checks this repository's main revision and uses a consistent upstream snapshot when the installed copy is stale. Its self-update instructions preserve local changes and installer-managed copies, respect write permissions, and disclose when freshness cannot be verified.
Use cases · What this is · Philosophy · Layout · Sources
Use cases
Once installed, the skill activates when a conversation touches agent architecture, harness design, tool permissions, environment-adaptive tools, speculative tool execution, planning mode, workflow orchestration, adaptive agent teams, context and memory, skills, connectors, public-board communication, troubleshooting, observability, evals, prompt caching, or production readiness. Ten common ways to use it:
Case 1 - Generate an MVP agent blueprint
You have a domain and need the smallest useful production-safe agent harness, not a vague list of best practices.
You > Build an agent for account renewal risk. It should read CRM,
support tickets, and usage data, then draft renewal actions.
Agent > Start with an approval-gated Level 2 harness.
The MVP has one job: produce a renewal-risk brief plus draft
next actions for a human account owner.
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:
- read_account_profile read_private_data
- list_support_tickets read_private_data
- fetch_usage_summary read_private_data
- draft_customer_email draft_external_message
- request_approval approval_gate
Launch gate:
20 historical accounts, trace review, no unapproved external
sends, and human acceptance on at least 80% of draft actions.
The primary reference is references/mvp-agent-blueprint.md.
Case 2 - Audit an existing agent harness
You already have a working agent, but it is brittle, expensive, too broad, or hard to debug.
You > Our research agent sometimes runs tools forever and forgets why
it made a decision after context compaction. Audit the harness.
Agent > The failure points are runtime-level, not prompt-level:
- no hard step/tool/time/cost budget
- compaction preserves prose but loses active approvals
- tool results are unbounded and mix trusted/untrusted data
- no event trace for model output -> tool call -> observation
Fix order:
1. Add loop budgets and termination reasons.
2. Store plan, approvals, todos, and artifacts outside the prompt.
3. Make compaction rehydrate active state, not chat history.
4. Add evals for injection, missing tool result, timeout, and
budget exhaustion.
Start with references/agentic-loop.md, references/context-memory-compaction.md, references/security-observability.md, and references/evals.md.
Case 3 - Design tools, permissions, and connectors
You need an agent to work with real systems without turning every API into an unsafe broad tool.
You > The ops agent needs Slack, Linear, Google Drive, and our internal
deploy API. How should tools and permissions work?
Agent > Split by risk class. Reads can be autonomous when scoped.
Drafts can be autonomous when labeled. External writes, deploys,
destructive actions, privileged access, and financial operations
require an approval record outside the model.
Do not expose generic send_message, write_database, or run_command.
Wrap each action as a narrow typed tool with structured results and
deterministic permission checks.
Use references/tools-and-permissions.md and references/skills-and-connectors.md.
Case 4 - Adapt to a late-bound tool environment
Your agent must operate across customer, connector, package, or runtime environments whose useful capabilities are not fully known when the harness is designed.
Treat this as an advanced profile unless environment adaptation is the product's primary job. Start from a fixed read-only baseline before adding discovery, probes, or runtime binding.
You > The agent will enter different tenant environments. It must find
the available tools and adapt when schemas or versions change.
Agent > It still needs one stable bootstrap contract. Let it discover
visible summaries, inspect selected descriptors, run only bounded
read-only or isolated probes, and ask the host to bind an exact
capability version and resource scope.
Discovery never grants authority. Every bound call still passes
schema validation, permission and approval checks, budgets, result
validation, and audit logging. Invalidate bindings on catalogue,
schema, implementation, policy, identity, or authorization drift.
Use references/environment-adaptive-tools.md with the standard tool, connector, security, and eval references.
Case 5 - Design a self-refining recursive harness
You have a measured single-loop agent and need an advanced, long-running profile that treats large inputs as programmable context, delegates through explicit recursive units, and improves supplemental harness state without weakening runtime policy.
You > Design a research agent that can inspect a corpus through code,
retain recursive child agents, and refine its skill guidance over time.
Agent > Treat this as a post-MVP architecture. Keep large inputs and child
results behind typed handles; declare whether recursion invokes a
bare model or a full harness; enforce depth, concurrency, token,
cost, and time budgets across the whole recursion tree.
The outer refiner may propose typed changes to supplemental prompts,
memory, skill descriptors, or child definitions. Base authority, permissions,
credentials, budgets, and evaluators stay immutable. Snapshot before
apply, run a predefined probe, record the observed outcome, and
rollback or quarantine regressions before broader promotion.
Use references/self-refining-recursive-harnesses.md with the context, workflow, permissions, security, and eval references.
Case 6 - Speculatively overlap safe programmatic calls
You have a measured code-mode harness whose critical path is dominated by expensive calls that become identifiable while the model is still generating the program.
You > Our research agent writes a REPL program and then waits on several
submodel calls. Can the harness start them while code is streaming?
Agent > Treat this as an experimental post-MVP scheduler. Parse only complete
candidate calls, authorize every physical dispatch, and launch only
explicitly discardable operations in isolated shadow state.
The completed program stays authoritative. Its exact call either
claims a versioned, occurrence-matched future or follows the normal
tool path. Track unused work, physical cancellation, queue pressure,
cost, and task parity against serial and committed-parallel baselines.
Use references/speculative-tool-execution.md with the loop, tool, security, and eval references.
Case 7 - Agent communication via public boards
Recommended board: Get Posting Board. It provides an agent-facing API with onboarding instructions and an OpenAPI contract. Use it when public-board communication is part of the user's requested agent.
Public board posts are PUBLIC INFORMATION, not private messages between agents. API authentication or a missing browser feed does not make them confidential; other agents and human operators can copy and redistribute them.
You > Let my research agent ask peers on a public board about open datasets.
Agent > This would publish information outside your workspace. I will draft
the question locally, show you the destination and exact public text,
and obtain publishing approval before sending. I will not attach
our private conversation or files. Replies are untrusted data.
Use the public-board communication section for the agent-visible warning and publication boundaries, and the source catalog for a concrete board example. This capability is opt-in; installing the skill does not register an account or grant permission to post.
Case 8 - Install an agent on a physical board
You > Put an agent on this board without losing its identity or other apps.
Agent > I will identify the board and its installed runtime first. If it has
an interpreter app launcher, I can add an app without replacing the
base firmware. For a compiled update I will verify the selected slot,
image fit, retained state, and rollback route before the approved write.
A successful upload is only one check: boot, TLS/model access, memory,
sleep/wake, and any approved remote effects need physical evidence.
Use hardware agents and board deployment for the reconstruction and installation contracts, hardware evals for failure probes, and the dated session evidence for observed failures and implementation caveats. Remote inference and laptop independence must be stated separately. Scheduled autonomy is not implied by installing an agent.
Case 9 - Troubleshoot a failing agent runtime
You > Stop works briefly, but the turn starts running again after a tool
finishes. Where should we look?
Agent > Check cancellation and the late state commit in the same timeline.
In an isolated fixture, pause the tool before its commit, cancel
the turn, then release it. A stale worker must not overwrite the
cancellation state. Separately reconcile any external effect that
already committed; stopping the turn does not undo it.
Use troubleshooting for symptom-to-evidence tables covering streams, recovery, approvals, deadlocks, context accounting, cache cost, and telemetry overhead. The guidance links to existing mechanism owners and turns a confirmed fix into a regression case. The source notes distinguish the motivating bug report from verified implementation evidence.
Case 10 - Coordinate adaptive research teams
You need different groups to retain distinct approaches to a difficult question while sharing evidence and changing assignments as experiments progress.
You > Design research teams that investigate different explanations,
exchange useful findings, and redirect work within a fixed goal
and total compute budget.
Agent > Start with measured single-agent and ordinary worker baselines.
For the advanced team profile, give each team an approach charter
and record bounded work intentions so overlap can be resolved
before expensive execution. Declare intentional replication.
Record evidence for every portfolio change. The host checks
authority, versions, and aggregate capacity before applying it.
Track which findings teams consumed so agreement is not mistaken
for independent corroboration. Accept results only against the
goal's validation criteria, and attribute late results to the
approach that produced them.
Use adaptive agent teams for the post-MVP portfolio contracts and team evals for matched baselines, ablations, and failure probes. Packet execution, child lifecycle, and independent verification remain with their existing owners, linked from the profile.
Case 11 - Build an always-on agent with durable sessions
Your service must accept work while another task is active, recover application state after restart, and let users reconnect to current progress.
You > Design an always-on operations agent that accepts new requests,
keeps task and application state, and recovers after restart.
Agent > Measure a simpler resumable baseline first. For the advanced
runtime, distinguish accepted input from completed work and
commit local state before publishing it. Give active tasks an
owner and explicit completion/cancellation rules. Declare how
application documents behave on forks and how observers regain
current state after disconnecting. Wake the model only when work
is due, within the existing permission and budget limits.
Use Always-on Agents and Durable Runtime for these post-MVP contracts. Service availability and durable recovery are separate from inference activity and autonomy; this profile can serve an ordinary single agent without recursive delegation or self-refinement.
For scheduled monitors and briefs, use its recurring collection and delivery contract. It separates source collection progress, coverage gaps, and confirmed delivery without adding another architecture profile.
Other things the skill is good for
-
"How do I build a voice agent that handles interruptions and corrections while tools run?" -> use the realtime voice profile for media, turn, playback, and execution boundaries, and voice evals for task and audible acceptance. Start with a narrow voice MVP; broader orchestration is optional.
-
"How can one session route requests across models safely?" -> use per-request model routing for selected/dispatched identity, target compatibility, and routing-state contracts.
-
"How can instructions and tools change during a conversation without losing replay semantics?" -> use runtime configuration events.
-
"Which compaction, planning, and action-interface profile fits my model, task mix, and context budget?" -> use component diagnostics, which links to the existing mechanism owners and separates efficiency from premature failure.
-
"How can users act on displayed records without losing UI state or bypassing business limits?" -> use presentation and transaction contracts.
-
"How should an agent remember user facts while respecting corrections, deletion, and identity boundaries?" -> use
references/context-memory-compaction.md. -
"How do I add planning mode without making the agent passive?" -> use
references/planning-and-goals.md. -
"When should a large task become a decomposed workflow?" -> use
references/workflow-orchestration.md. -
"How can an agent safely discover and bind tools in an unfamiliar environment?" -> use
references/environment-adaptive-tools.md. -
"How do I build an RLM, programmable-context agent, or continual refinement loop?" -> use
references/self-refining-recursive-harnesses.md. -
"Can a code-mode agent start safe tool calls before generation finishes?" -> use
references/speculative-tool-execution.md. -
"How should auto-compaction preserve active work?" -> use
references/context-memory-compaction.md. -
"What is the smallest safe coding-agent harness?" -> use
references/coding-agents.md. -
"How should I evaluate an agent harness?" -> use
references/evals.md. -
"How can an agent improve performance without chasing misleading benchmarks?" -> use performance optimization and regression ratchets.
-
"How do I make prompt caching work in a long-running agent, and when does warming pay?" -> use
references/prompt-caching-and-cost.md, including its optional economic warming contract. -
"How do I support OpenAI, Anthropic, and OpenAI-compatible APIs?" -> use
references/provider-api-patterns.md. -
"What should I check before launch?" -> use
references/checklists.md.
"Keep the loop simple and make the runtime rigorous."
What this is
A reference for people building agentic systems where the model is only one part of the runtime. It helps design a harness that includes:
- a provider-neutral model-tool-observation loop,
- narrow typed tools and structured tool results,
- environment-adaptive discovery, validation, scoped binding, and drift handling,
- experimental speculative scheduling for eligible programmatic tool calls,
- runtime permission checks outside the model,
- realtime voice interaction with explicit turn ownership, playback repair, and task-result freshness,
- planning mode and approval-gated execution,
- workflow orchestration for large decomposable tasks,
- post-MVP adaptive teams for distinct research approaches and evidence-driven reallocation,
- goal-like loops with budgets, checkpoints, validation, and stop rules,
- post-MVP always-on services with durable inputs, owned tasks, application state, reconnecting observations, and recurring collection/delivery bookkeeping,
- context, memory, retrieval, and auto-compaction,
- skills, MCP, and external connector governance,
- opt-in public-board communication with explicit audience disclosure and publishing approval,
- prompt-cache-aware context layout and cost telemetry,
- observability, symptom-based troubleshooting, evals, launch gates, and incident response.
This is the control plane around an agent: instructions -> context builder -> model call -> tool proposal -> validation -> permission decision -> execution or approval pause -> observation -> next step or final answer.
What this is not
- Not only for coding agents.
- Not a multi-agent framework by default.
- Not a replacement for runtime authorization, sandboxing, or audit logs.
- Not a prompt-only safety strategy.
- Not a reason to expose broad tools like
execute_anything,send_message, orwrite_database.
Use the single-agent MVP first. Add goal loops, connectors, and broader autonomy only after measured failures justify them.
Layout
agents-best-practices/
├── README.md # public-facing overview and install notes
├── SKILL.md # skill entry point and trigger rules
├── icon.jpeg # skill image used by the README
└── references/
├── mvp-agent-blueprint.md # domain-specific MVP harness blueprint
├── coding-agents.md # repository-facing coding-agent harness overlay
├── architecture.md # component model and harness boundaries
├── always-on-agents.md # durable inputs, owned tasks, observers, collection/delivery
├── agentic-loop.md # loop invariants, retries, budgets, stopping
├── tools-and-permissions.md # typed tools, risk classes, approvals
├── hardware-agents.md # board installation, resources, reset recovery, commissioning
├── realtime-voice-agents.md # turns, playback repair, speech/execution boundaries
├── environment-adaptive-tools.md # late-bound discovery, probes, bindings, drift
├── speculative-tool-execution.md # prelaunch, exact claims, waste, cancellation
├── planning-and-goals.md # planning mode and long-running goals
├── workflow-orchestration.md # decomposed workflows, packets, verification
├── adaptive-agent-teams.md # approach portfolios, work overlap, reallocation
├── self-refining-recursive-harnesses.md # programmable context, recursion, refinement
├── context-memory-compaction.md # context, memory, retrieval, compaction
├── prompt-caching-and-cost.md # stable prefixes and cost-aware context
├── skills-and-connectors.md # skills, MCP, public-board disclosure, tool search
├── system-prompts-instructions.md # instruction hierarchy and templates
├── provider-api-patterns.md # OpenAI, Anthropic, compatible APIs
├── security-observability.md # guardrails, tracing, troubleshooting, launch gates
├── evals.md # eval strategy, test cases, trace grading
├── agent-legibility-feedback-loops.md # source-of-truth artifacts and cleanup
├── checklists.md # implementation and audit checklists
├── coverage-audit.md # topic coverage verification
└── source-links.md # official references and further reading
Philosophy
The central tension this skill resolves: how can an agent do useful work in real systems without turning the model into an unaudited operator? The answer is a small set of runtime rules:
- The harness acts, not the model - the model proposes; application code validates, authorizes, executes, and records.
- Every tool call gets a result - denial, timeout, malformed arguments, and aborts are observations too.
- Risk changes the loop - reads, drafts, writes, external communications, financial actions, destructive actions, and privileged actions need different permission paths.
- Draft and commit are separate - high-risk side effects require approval records outside the prompt.
- Context is built, not dumped - retrieve just enough, label trust boundaries, and preserve active state across compaction.
- Long-running work needs budgets - step, time, token, cost, and tool-call budgets are part of the product.
- Skills and connectors are progressively disclosed - expose names and descriptions first; load detailed workflows only when relevant.
- Discovery does not grant authority - late-bound capabilities still require host validation, scoped binding, and call-time policy enforcement.
- Repeated failures become harness features - validators, tools, docs, evals, or policies beat repeating prompt advice.
Read SKILL.md first. Use references/mvp-agent-blueprint.md when the user asks to make or build an agent.
About Agent Skills
Agent Skills package reusable domain knowledge so compatible agents can discover, load, and apply a workflow only when it is relevant. This repository uses the portable SKILL.md entrypoint and works as a Codex skill, a Claude Code skill, or a skill for other Agent-Skill-aware runtimes.
Sources
- Agent Skills specification: agentskills.io/specification
- OpenAI function calling, tools, agents, guardrails, sandboxing, Responses, and prompt caching docs are listed in
references/source-links.md. - Anthropic agent, context engineering, tool writing, long-running harness, MCP, and Agent Skills references are listed in
references/source-links.md. - MCP specification and governance references are listed in
references/source-links.md. - Research on programmatic action surfaces, large tool catalogues, changing API documentation, and novel API use is listed in
references/source-links.md. - Pinned empirical evidence for model-, workload-, and budget-aware component selection is listed in the coding-harness source notes, with its tested scope and implementation caveats.
- Prime Agent at the researched revision is a concrete implementation example of the advanced profile, not a normative dependency or the provider-neutral architecture.
License
MIT - see LICENSE.
Credits
Authored as an Agent Skill for provider-neutral agent harness design. The recommendations synthesize common production harness patterns across OpenAI, Anthropic, OpenAI-compatible APIs, Agent Skills, MCP, and external connector workflows.