Agents Best Practices
A provider-neutral Agent Skill for designing, generating, auditing, and refactoring agentic harnesses.
Evidence shows: README and SKILL.md emphasize least privilege, such as narrow typed tools, permission checks outside the model, and risk classification (reads, drafts, writes, external communications, etc.). User confirmation is implemented via approval gates and draft/commit separation. Data flow transparency is shown through event tracing and structured observations. Sensitive data handling is addressed via trust boundary labeling and context building principles. Dependency security: installation uses npx and git clone, no dependency locking or vulnerability scanning mentioned, so deducted. External effects are controlled via approval gates and risk classification. Rollback: no explicit rollback mechanism mentioned, only audit logs, so deducted. Source attribution is provided via source-links.md and references to official docs.
Evidence shows: Documentation is internally consistent, philosophy principles align with reference docs. Dependency availability: relies on external services (e.g., npx skills) and unpinned versions, introducing uncertainty, so deducted. Failure messages: docs emphasize tool call results (denials, timeouts, malformed args) as observations, but no specific error message templates, so deducted.
Evidence shows: Target audience is clear (developers building agent systems), scenarios cover MVP blueprint, audit, tool design, etc. Capability boundaries are defined via 'What this is not'. Trigger precision: SKILL.md has trigger rules but content not provided, so deducted. Environment fit: supports Codex, Claude Code, and other compatible runtimes, but no specific configuration details, so deducted.
Evidence shows: Information architecture is clear with README, SKILL.md, references/ directory. Install notes are detailed with multiple methods. Naming stability: no versioning or naming conventions mentioned, so deducted. Examples and FAQ are provided via use cases and common questions. Known limitations are addressed via 'What this is not' and philosophy. License is MIT, clear. Versioning/changelog missing, so deducted. Maintenance responsibility: author unverified but GitHub provided, so deducted.
Evidence shows: Output usability via concrete blueprints, checklists, and reference docs. Marginal value via provider-neutral best practices, avoiding reinvention. Cost-benefit via emphasis on budgets and cost telemetry, but no specific cost data, so deducted.
Evidence shows: Claims are traceable via source-links.md referencing official docs. Cross-source corroboration: relies only on official docs, no independent verification, so deducted. Fact/inference separation: docs distinguish recommendations from sources, but not explicitly labeled, so deducted.
- Dependencies are not pinned, installation may introduce supply chain risks.
- No rollback mechanism provided; audit logs are insufficient for recovery.
- No changelog provided, making updates hard to track.
- Publisher identity unverified, maintenance responsibility unclear.
What does this agent do, and when should you use it?
agents-best-practices is an Agent Skill with a SKILL.md entrypoint that provides a comprehensive reference for agent runtime design. It covers the model-tool-observation loop, typed tools, permission checks, planning mode, workflow orchestration, context-memory-compaction, prompt caching, observability, evals, and launch checklists. The repository contains a main SKILL.md file and a references/ directory with dedicated guides on topics like MVP blueprints, coding agents, security, and evals. It is designed to be compatible with Codex and Claude Code, and can be installed manually or via npx skills.
Once installed, the skill activates when a conversation touches agent architecture. It provides reference guides for generating MVP agent blueprints (references/mvp-agent-blueprint.md), auditing and fixing existing implementations (references/agentic-loop.md, etc.), designing tools and permissions (references/tools-and-permissions.md), and implementing planning mode, workflows, context compaction, prompt caching, evals, and launch checklists. It responds to prompts like 'Build an agent for...' or 'Audit this agent...' by pointing to the appropriate reference files.
- A product manager wanting to generate a minimal-viable agent blueprint for a specific domain like account renewal risk, with approval-gated workflows.
- An engineer with a brittle agent (e.g., a research agent) who wants to audit runtime failures (e.g., unbounded tool loops, state loss after compaction) and apply fixes.
- An engineer developing an ops agent who needs to design tools and permissions for Slack, Linear, and internal APIs with risk classification.
- A developer wanting to implement planning mode without making the agent passive, or to decompose large tasks into workflows.
- A developer working on optimizing prompt caching and cost in long-running agents.
- A team preparing an agent for production who needs launch checklists and evaluation strategies.
What are this agent's strengths and limitations?
- Provider-neutral: compatible with Codex and Claude Code, following the portable SKILL.md spec.
- File-based reference, no external service or API keys required.
- Covers runtime discipline beyond prompting: tool permissions, budgets, compaction, evals.
- Emphasizes narrow typed tools and safety checks, reducing risk of unintended side effects.
- Requires manual installation (cloning to specific directories), not in an official marketplace, and requires user action.
- As a reference, it requires adaptation to specific codebases and runtime environments.
- Relies on the Agent Skills ecosystem, which may limit support for non-compatible agents.
- Documentation is reference material, not an automated executable; users must implement tips themselves.
How do you install or deploy this agent?
Install with one of the following:
A. Using npx skills (requires Node.js):
npx skills add DenisSergeevitch/agents-best-practices -gB. 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-practicesHow do you use this agent?
Once installed, the skill activates when a conversation touches agent architecture. For an MVP blueprint, say 'Build an agent for [domain]' and the skill will guide you through references/mvp-agent-blueprint.md. To audit an existing agent, describe its symptoms and the skill will reference files like references/agentic-loop.md and references/security-observability.md. To design tools and permissions, specify your systems and the skill uses references/tools-and-permissions.md. You can also ask direct questions like 'How do I add planning mode?' and the skill will direct you to the relevant reference.