agents-best-practices: a provider-neutral Agent Skill for designing agent harnesses

The problem: agent failures that live in the runtime, not the prompt

Most agent debugging starts in the wrong place. Teams rewrite system prompts when the actual defect is that the loop has no step budget, that tool results arrive unbounded, or that context compaction throws away an approval the user granted twenty turns ago. The README frames this directly with its opening line: "The model proposes actions; the harness validates, authorizes, executes, records, and returns observations." That sentence is the whole thesis. The model is one component; the harness is the system around it.

The repository targets people who own that harness. The README lists research, support, operations, sales, finance, data analysis, procurement, legal, healthcare, education and workflow automation as domains that "all need the same core runtime discipline," so the intended reader is not only someone building a coding agent. If you are writing an agent that reads a CRM and drafts a renewal email, you are in scope. If you are tuning a single prompt for a classification task, you are not.

How the skill works: an on-demand reference set, not a runtime

An Agent Skill in this format is a directory the host agent scans. The repository layout confirms the shape: SKILL.md at the top level, an icon.jpeg, and a references/ directory holding the substantive material. 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 activation model matters for cost. The host agent reads the skill description, decides relevance, and then pulls specific reference files rather than loading everything. The README points at named files for named problems: references/mvp-agent-blueprint.md for greenfield design, references/agentic-loop.md, references/context-memory-compaction.md, references/security-observability.md and references/evals.md for audits, references/tools-and-permissions.md and references/skills-and-connectors.md for tool surface design. The data flow is therefore conversational: your question, the agent's decision to consult a file, the file's guidance, and a response shaped by it. Nothing executes. There is no daemon, no server, no SDK to import.

The README's worked examples show the intended output format. Asked to build a renewal-risk agent, the skill produces a level-2 approval-gated harness with a named core loop (context builder, model call, typed tool call, schema validation, permission check, execution or pause, structured observation) and a minimal tool list where each tool carries a risk class such as read_private_data, draft_external_message or approval_gate. That is a design artifact, and the README presents it as the deliverable.

Installing agents-best-practices for Codex or Claude Code

The README gives three install routes. The first uses the skills CLI from vercel-labs and works with any compatible agent:

npx skills add DenisSergeevitch/agents-best-practices -g

The -g flag installs at user level, which the README says makes the skill discoverable from every project rather than one repository.

If you prefer a plain clone, the README documents the per-agent paths. For Codex it respects CODEX_HOME and falls back to ~/.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"

For Claude Code at user level, the target directory is ~/.claude/skills. A project-level variant clones into .claude/skills inside the repository instead, which scopes the skill to that project. After cloning, check that SKILL.md, icon.jpeg and the references/ directory are all present, because the README's own verification step calls out exactly those three items.

A first real use looks like the README's audit case. Describe your harness and its symptoms in plain language, for example that the agent runs tools indefinitely and forgets decisions after compaction, and ask for an audit. The expected response is a list of runtime-level failure points with a fix order, not prompt edits. If you get generic advice back, the skill was probably not loaded; confirm the install path against the directory your agent reads.

Where the guidance stops being useful

The repository contains documents. It does not contain a harness. If your problem is that you need loop budgets enforced in code, this skill will tell you to add them and describe why, but you still write the enforcement. A team expecting an importable library or a scaffold generator will be disappointed, and the README does not claim otherwise.

There is a second, subtler limit. The README itself flags the late-bound tool environment case as advanced: "Treat this as an advanced profile unless environment adaptation is the product's primary job." That is an honest warning, and it cuts both ways. If runtime discovery of tools across tenant environments is your core problem, the fixed baseline the skill recommends may be exactly the constraint you cannot accept.

Finally, the README is thin on the reference files themselves. It names several, but the full contents of references/ are not reproduced in the README, so you cannot judge coverage of, say, evals or observability without opening the files. The README also does not document rollback or an uninstall path for the skill, so removal means deleting the directory you cloned.

agents-best-practices compared with a framework like LangGraph

The obvious alternative is a code framework: LangGraph, the OpenAI Agents SDK, or similar libraries where the loop, state and tool dispatch are implemented for you. The difference in approach is the axis of the deliverable. A framework gives you a graph or an agent class you instantiate, and its documentation tells you which callbacks to implement. This repository gives you prose guidance that your existing coding agent reads and applies to whatever you are building, including a harness you wrote by hand.

That makes the two complementary rather than competing. If you are already on LangGraph, the reference files on loop budgets, compaction and permission classes still describe failure modes your graph can exhibit, and the audit fix order is framework-agnostic. What you will not get here is a state machine, checkpointing, or a tool-calling runtime. Pick this repository when the design is unsettled and you want a second opinion inside your editor; pick a framework when the design is settled and you need it to run.

Licence, maintenance and what an upgrade costs you

The repository is MIT licensed, and the README carries the standard MIT badge. For a directory of markdown files that your agent reads locally, the practical implication is narrow: you can copy, modify and redistribute the text, including inside a commercial product, provided the licence terms are honoured. This is not legal advice; read LICENSE if the distinction matters to your organisation.

Maintenance is a different question. The last push to the default branch was on 2026-09-05, and the repository is not archived. There are no retrieved releases, so there is no version to pin and no changelog to read before upgrading. An upgrade is therefore a git pull on the cloned directory, and the cost of that is re-reading whichever reference files your workflow depends on, because nothing in the repository signals which files changed. If you fork the skill to add your own house rules, budget time for merging against upstream by hand.

Editorial conclusion

Adopt it if you are designing or auditing an agent harness and want a structured checklist that your existing coding agent can read: install with npx skills add DenisSergeevitch/agents-best-practices -g, then point the conversation at the reference file that matches your problem. Skip it if you need a runnable runtime, a framework to import, or a single flat document, because the repository ships guidance in references/ rather than executable code. Before relying on it, verify that the install path matches the directory your agent actually reads, and check the references/ directory for the specific file covering your failure mode, since the README only names a handful of them.

Frequently asked questions

Official sources

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