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

Most agent skills teach the model to write better prompts. DenisSergeevitch/agents-best-practices instead teaches you that the model is one part of a runtime — and the more important part is the harness around it.

Why This Skill Matters

The README's central line: "The model proposes actions; the harness validates, authorizes, executes, records, and returns observations." That sentence is the whole philosophy in one breath. The skill is built for designing, generating MVP blueprints for, auditing, refactoring, and explaining agentic harnesses — and the README explicitly says it applies beyond coding agents (research, support, operations, sales, finance, data analysis, procurement, legal, healthcare, education, workflow automation).

The repository has 2.2k stars on GitHub and is MIT-licensed. It targets Codex, Claude Code, and other Agent-Skill-aware runtimes via a portable SKILL.md entrypoint.

The skill ships 21 reference docs in references/, organized so you can dive into the slice you need:

• mvp-agent-blueprint.md — domain-specific MVP harness blueprint
• coding-agents.md — repository-facing coding-agent overlay
• architecture.md — component model and harness boundaries
• agentic-loop.md — loop invariants, retries, budgets, stopping
• tools-and-permissions.md — typed tools, risk classes, approvals
• 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
• 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 — Agent Skills, MCP, connectors, tool search
• system-prompts-instructions.md — instruction hierarchy and templates
• provider-api-patterns.md — OpenAI, Anthropic, compatible APIs
• security-observability.md — guardrails, tracing, 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

Nine philosophy rules sit underneath. Pick the ones you need:

1. The harness acts, not the model — the model proposes; application code validates, authorizes, executes, and records.
2. Every tool call gets a result — denial, timeout, malformed arguments, and aborts are observations too.
3. Risk changes the loop — reads, drafts, writes, external communications, financial actions, destructive actions, and privileged actions need different permission paths.
4. Draft and commit are separate — high-risk side effects require approval records outside the prompt.
5. Context is built, not dumped — retrieve just enough, label trust boundaries, and preserve active state across compaction.
6. Long-running work needs budgets — step, time, token, cost, and tool-call budgets are part of the product.
7. Skills and connectors are progressively disclosed — expose names and descriptions first; load detailed workflows only when relevant.
8. Discovery does not grant authority — late-bound capabilities still require host validation, scoped binding, and call-time policy enforcement.
9. Repeated failures become harness features — validators, tools, docs, evals, or policies beat repeating prompt advice.

Installation

The README's primary install path is the npx skills CLI:

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

The -g flag installs globally at user level so every project can discover it. Without it, the install is project-scoped.

If you cannot use the skills CLI, the README documents manual paths for both Codex and Claude Code (user- and project-level). For Claude Code at user level:

mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

Real Workflow: Generate an MVP Blueprint for a Real Domain

You have a domain (say, account renewal risk) and need the smallest production-safe harness for it, not a vague list of best practices.

Step 1. Phrase the request:

Build an agent for account renewal risk. It should read CRM, support tickets, and usage data, then draft renewal actions.

Step 2. The skill leads the agent to start from an approval-gated Level 2 harness with one job — produce a renewal-risk brief plus draft next actions for a human account owner. The MVP loop the skill gives you:

user/task -> context builder -> model call -> typed tool call
  -> schema validation -> permission check -> execution or pause
  -> structured observation -> next step or final brief

Step 3. The minimal toolset the skill suggests: a read tool per data source (read_account_profile, list_support_tickets, fetch_usage_summary), one draft tool (draft_customer_email), and one approval gate (request_approval). No broad send_message or write_database — typed, scoped, auditable.

Step 4. Define a launch gate before going to users: a fixed historical corpus (e.g. 20 accounts), trace review, no unapproved external sends, and human acceptance on a target share of draft actions (the example gate is 80%).

Step 5. Keep the mvp-agent-blueprint.md reference open while you implement — every decision in the blueprint comes from there. Before opening it, replay the loop in your head: context → model → typed tool → validation → authorization → execute-or-pause → structured observation → next step or final brief; a missing stage is an MVP gap.

Real Workflow: Audit a Brittle Existing Agent

You already have a research agent that runs tools forever and forgets why after context compaction. The harness is the problem, not the prompt.

Step 1. Phrase the audit:

Our research agent sometimes runs tools forever and forgets why it made a decision after context compaction. Audit the harness.

Step 2. The skill points at runtime-level failure modes, not prompt-level ones: 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.

Step 3. The skill's 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.

Step 4. Each fix maps to a specific reference — agentic-loop.md, context-memory-compaction.md, security-observability.md, and evals.md. Open the relevant reference before implementing the fix; the README is the index, the references are the how. Add an eval for each fix — injection, missing tool result, timeout, and budget exhaustion are the four failure classes the README names.

Tips

• Treat the skill as an index — the README's use cases tell you which of the 21 reference docs to open.
• Use the "risk changes the loop" rule to justify every typed tool: if it does not fit a risk class, it should not exist as a single broad tool.
• Approval records belong outside the prompt — keep them in durable store keyed by request, not in the model's chat history. Otherwise approvals are lost the moment the context window rolls over or is compacted, and the model will believe it can re-issue side effects.
• Compaction should rehydrate active state (todos, plans, approvals) — never preserve chat prose at the cost of dropping state. The context-memory-compaction.md reference is the deep-dive for this — align your compaction implementation with it.
• Budgets (step, time, token, cost, tool-call) are part of the product spec, not an optimization pass. The README's "What this is" section lists budget-adjacent pieces — planning mode, approval-gated execution, workflow orchestration — as first-class harness components, not add-ons.

When Not to Use This

If you are looking for a multi-agent orchestration framework, the README explicitly says this skill is "not a multi-agent framework by default" — use the single-agent MVP first. If your goal is to bypass runtime authorization, sandboxing, or audit logs with prompt-only safety, the README states the skill is "not a replacement for runtime authorization, sandboxing, or audit logs" — start there instead. And per the same section, it is not a reason to expose broad tools like execute_anything, send_message, or write_database — wrap actions as narrow typed tools instead. If you only need help writing a single prompt for one task, this skill is heavier than the job.

See the leaderboard for more skills.