The Problem

Agentic harness design lacks a provider-neutral foundation that simultaneously addresses runtime discipline, tool permissioning, and production readiness. Teams building agents for CRM, support, or operations workflows frequently reconstruct permission schemas, approval gates, and context-management patterns from scratch, resulting in inconsistent safety boundaries and uneven observability across projects.

What This Does

This repository provides a provider-neutral Agent Skill (20 files, 17 Markdown) that functions as a reusable harness template rather than a prescriptive framework. The core reference, references/mvp-agent-blueprint.md, documents a minimal production-safe agent loop: user/task → context builder → model call → typed tool call → schema validation → permission check → execution or pause → structured observation → next step or final brief. Supporting references cover the full stack: references/skills-and-connectors.md maps tool integration patterns, references/tools-and-permissions.md defines read/vs. write boundaries, references/security-evals-observability.md outlines evals and observability hooks, and references/prompt-caching-and-cost.md addresses caching strategies and cost control. The skill is designed to activate when agent architecture or harness design comes up in a conversation, functioning as a drop-in knowledge layer for Codex, Claude Code, or any compatible agent runner.

How It Is Wired

Control flows through a Level 2 approval-gated loop documented in references/mvp-agent-blueprint.md: an entry point receives a user task, a context builder aggregates CRM, ticket, and usage data, the model produces typed tool calls, schema validation runs against defined contracts, a permission check gates external sends (e.g., draft_customer_email), and observations are recorded before the next step is determined. The harness does not execute code itself; it provides the control-flow contract that an agent runner (Codex, Claude Code, or a custom harness) implements. references/provider-api-patterns.md documents how to wire provider-specific calls without hardcoding them, and references/system-prompts-instructions.md standardizes instruction formatting across models. No entry-point script or main function exists in the repository—wiring is left to the consumer harness.

How To Use It

Installation follows the README three-path approach. Via the skills tool:

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

Or clone manually into a user-level skills directory:

# 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"

After install, verify SKILL.md, icon.jpeg, and references/ are present. The skill then activates when the agent discusses harness design, tool permissions, planning mode, context and memory, skills, connectors, observability, evals, prompt caching, or production readiness.

Real-World Use

Account renewal risk agent (per the README use-case): The agent reads CRM profiles, lists support tickets, and fetches usage summaries—all read-private-data operations. The MVP harness is Level 2: every external action (e.g., draft_customer_email) passes through request_approval (approval_gate). After 20 historical accounts are traced and no unapproved external sends occur, a human accepts at least 80% of draft actions. Core tools: read_account_profile, list_support_tickets, fetch_usage_summary, draft_customer_email, request_approval. The agent produces a renewal-risk brief plus draft next actions for the account owner, with structured observations recorded at each loop iteration.

Code Health & Issues

  • No test files detected – untested code paths repository-wide
  • No CI/CD pipeline detected – no automated build/test gate; .github/ or CI config absent
  • No Dockerfile – no container build artifact
  • No lockfile – dependency versions not pinned in a lockfile

License: MIT is present (LICENSE). Committed secrets: none found.

The Bottom Line

This is a lightweight, provider-neutral skill that maps the control-flow and permission-discipline layer an agent harness requires, without prescribing a runtime or wiring infrastructure. It is most useful as a reference for designing or auditing agent architectures rather than a drop-in execution framework. Teams that already have a runner (Codex, Claude Code, or custom) and need a structured playbook for MVP blueprints, permission schemas, and observability hooks will find it practical; teams seeking a complete, test-gated, CI-integrated framework will need to add the missing SDLC pieces.