agents-best-practices: A Provider-Neutral Skill for Designing Agent Harnesses

The problem is harness discipline, not prompt quality

Most agent failures that get blamed on prompts are described here as runtime failures. The README's second use case is explicit: a research agent that "sometimes runs tools forever and forgets why it made a decision after context compaction" is diagnosed as having no hard step, tool, time or cost budget, compaction that preserves prose but drops active approvals, unbounded tool results that mix trusted and untrusted data, and no event trace linking model output to tool call to observation. None of those are fixed by rewriting the system prompt. The skill targets the layer underneath: the loop, the permission checks, the observation format and the trace. The stated audience is broad on purpose. The README claims it applies beyond coding agents to research, support, operations, sales, finance, data analysis, procurement, legal, healthcare, education and workflow automation. What those domains share, in this framing, is the same core runtime discipline rather than a shared prompt style.

The core loop the skill keeps returning to

The README states the central claim as a quote: "The model proposes actions; the harness validates, authorizes, executes, records, and returns observations." The MVP example expands that into a pipeline: user/task to context builder to model call to typed tool call to schema validation to permission check to execution or pause to structured observation to next step or final brief. Two things in that chain are opinionated. First, tool calls are typed and schema-validated before anything executes, so a malformed call is a validation failure rather than a runtime surprise. Second, the permission check sits between validation and execution, which means an approval pause is a first-class state of the loop and not an error path. The README's audit guidance follows from that: "Store plan, approvals, todos, and artifacts outside the prompt." If approvals live only in the conversation, compaction erases them. That is the mechanism the skill is selling, and it is a design position rather than a library.

Risk classes instead of generic tools

The third use case is the most concrete part of the README. Asked how an ops agent should handle Slack, Linear, Google Drive and an internal deploy API, the skill answers by splitting tools 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." The MVP example shows the naming convention that follows: read_account_profile and list_support_tickets carry read_private_data, draft_customer_email carries draft_external_message, request_approval carries approval_gate. The README also states a prohibition directly: "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. Whether that granularity is workable depends on how many actions your product has; a tenant with hundreds of API endpoints will find one-tool-per-action expensive to maintain, and the README does not address that scaling case.

Install paths and what actually lands on disk

The README gives three install routes. With the vercel-labs skills CLI: npx skills add DenisSergeevitch/agents-best-practices -g, where -g installs at user level so every project can discover it. Alternatively, a paste-in prompt instructs an agent to clone the repository into the user-level skills directory and verify that SKILL.md, icon.jpeg and the references/ directory are present. Manual installs are given per harness: for Codex, mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" followed by a git clone into "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"; for Claude Code at user level, the same pattern under $HOME/.claude/skills; for Claude Code at project level, .claude/skills. The repository layout implied by the README is SKILL.md plus a references/ directory containing at least mvp-agent-blueprint.md, agentic-loop.md, context-memory-compaction.md, security-observability.md, evals.md, tools-and-permissions.md and skills-and-connectors.md. The primary language field is listed as unknown, and the material does not show any executable code, so treat this as a documentation package delivered through the Agent Skill convention.

Activation is broad, and that is a design choice with a cost

The README says the skill activates when a conversation touches agent architecture, harness design, tool permissions, environment-adaptive tools, speculative tool execution, planning mode, workflow orchestration, context and memory, skills, connectors, public-board communication, observability, evals, prompt caching, or production readiness. That is a wide trigger surface. It means the skill will load into conversations that only brush against one of those topics, which is fine if the reference files are short and bad if they are long, since the activated content competes with the task at hand for context. The README does not state how large the references are or whether the skill loads them selectively. If you install it globally with the -g flag, that activation surface applies to every project on the machine. Project-level installation under .claude/skills is the narrower option the README documents, and it is the one worth preferring until you know how the activation behaves in your own sessions.

The advanced profile is explicitly gated

The fourth use case covers late-bound tool environments, where an agent enters customer, connector, package or runtime environments whose useful capabilities are not known when the harness is designed. This is the part of the README that shows the most restraint. It instructs: "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." That is a deliberate ordering, and it is the opposite of what a discovery-first design would do. The trade-off is real: a fixed read-only baseline is safer and cheaper to test, but it will not serve a product whose selling point is adapting to arbitrary tenants. The README's own text is truncated mid-sentence in this section, so the discovery, probing and runtime-binding mechanics are not described in the material available. Anyone whose product is environment adaptation should read references/skills-and-connectors.md before assuming the skill covers their case.

What it is not, and what to use instead

This repository does not execute anything. It is a set of markdown references plus a SKILL.md that an agent reads. If you want runtime enforcement of loop budgets, schema validation or approval gates, you need a framework that owns the loop, such as the agent runtimes shipped by Anthropic or OpenAI, or a general orchestration library like LangGraph, where the loop, state and checkpoints are code you can unit test. The difference in approach is direct. A framework makes the discipline executable and testable; this skill makes it describable, reviewable and portable across harnesses. The portable part is the point: the same references apply whether the host is Codex or Claude Code, and the README markets it as provider-neutral. But neutrality also means nothing stops a model from ignoring the guidance on a given turn. If your failure mode is an agent that actually runs tools forever, a document will not stop it. A budget check in the loop will. Use the skill to decide what to build, then build it somewhere that can enforce the decision.

Maintenance, versioning and licence

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the standard permissive arrangement, but it says nothing about the provenance of the reference content, and the README's Sources section is referenced in its table of contents without its contents being available here. Check what that section cites before reusing the text inside a product. On maintenance: the last push shown is 2026-09-05, the repository is not archived, and no releases were retrieved. There is no version number, no changelog and no tag to pin. If you clone it into a skills directory, you are tracking the main branch, and an update arrives as a change to files your agent reads at activation time. Pin a commit hash in your clone if you need reproducibility, and re-read the diff before pulling, because a silent change to a permission-class recommendation is the kind of edit that should not land unnoticed in a production harness.

Editorial conclusion

Adopt it if you are designing or auditing an agent harness and want a vocabulary for the runtime layer: typed tools, risk classes, loop budgets, compaction that rehydrates state, and evals for injection and budget exhaustion. Skip it if you want a runtime library, a framework, or anything that executes on your behalf; this repository is documentation plus a SKILL.md entry point. Before relying on it, open references/mvp-agent-blueprint.md and references/tools-and-permissions.md and check whether the permission classes and launch gates match your own risk model, because the README shows no release history and no versioned changelog to diff against.

Official sources

1. DenisSergeevitch/agents-best-practices on GitHub
2. Issues
3. License: MIT
4. README