The references below are the primary authoritative sources used throughout this documentation. Use Agent Skills links when working on skill format, metadata, progressive disclosure, descriptions, and skill evals. Use OpenAI links for API implementation patterns, function calling, hosted tools, guardrails, sandboxes, prompt caching, and harness engineering practices. Use Anthropic links for simple agent patterns, context engineering, tool ergonomics, long-running harnesses, MCP execution, and skill architecture. Use MCP links for external resources, prompts, tools, authorization, and connector design. For threat modeling, governance, and enterprise deployment controls, consult the security and governance references at the end of this page.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/DenisSergeevitch/agents-best-practices/llms.txt
Use this file to discover all available pages before exploring further.
Agent Skills
Agent Skills specification
The Agent Skills specification — the authoritative reference for skill format, required frontmatter fields, file structure, and loader behavior.
Creator best practices
Best practices for writing skills that agents activate reliably and execute correctly. Covers instruction density, progressive disclosure, and validation.
Optimizing skill descriptions
How to write skill descriptions that match the right tasks and avoid false activations. Essential for skills that share semantic territory.
Evaluating skill output quality
How to design activation evals and output quality evals for skills, including grading criteria and regression testing.
Using scripts in skills
How to bundle executable scripts into a skill and invoke them safely from skill instructions.
OpenAI
Agents guide
OpenAI’s primary guide to building agents with the Responses API, including tool use, multi-step reasoning, and hosted tools.
Function calling
How to define and call functions (tools) using the OpenAI API, including strict mode, parallel calls, and structured outputs.
Tools
Reference for all built-in and custom tool types available in the OpenAI API, including web search, code interpreter, and file search.
Guardrails and human review
How to implement input and output guardrails, configure human review checkpoints, and manage approval flows for risky agent actions.
Agent safety
OpenAI’s safety guidelines for agent builders, covering threat modeling, permission boundaries, and responsible deployment practices.
Sandboxed agents
How to run agent code execution in sandboxed environments, including filesystem and network isolation.
Responses API migration
Migration guide from the Completions API to the Responses API for agent harnesses.
Prompt caching
How prompt caching works in the OpenAI API, including cache key behavior, TTLs, and how to structure prompts for maximum cache hits.
Prompt Caching 201
Advanced cookbook examples for prompt caching, including multi-turn agents, system prompt versioning, and cache telemetry.
Harness engineering
OpenAI engineering article on building production agent harnesses, covering architecture patterns, reliability, and operational practices.
MCP and connectors
How to connect external tools and MCP servers to OpenAI agents, including namespacing, scoping, and approval configuration.
Anthropic
Building effective agents
Anthropic’s foundational research article on agent design — covering when to use agents, how to structure tool use, and how to avoid over-engineering.
Effective context engineering
How to structure context for long-running agents: instruction hierarchy, cache-aware ordering, compaction, and state management.
Writing effective tools
How to write tool descriptions, schemas, and error responses that improve tool selection accuracy and reduce misuse.
Long-running agent harnesses
Engineering patterns for harnesses that run for minutes or hours, covering budgets, checkpointing, compaction, and recovery.
Code execution with MCP
How Anthropic approaches sandboxed code execution through MCP, including security boundaries and result handling.
Agent Skills engineering note
Anthropic’s engineering note on Agent Skills — the motivation, design, and how skills equip agents for real-world tasks.
MCP
MCP specification
The Model Context Protocol specification (2025-11-25). The authoritative reference for MCP transport, message format, capabilities, and lifecycle.
MCP authorization
The authorization section of the MCP specification — how clients and servers negotiate credentials, scopes, and access control.
MCP tools
The tools section of the MCP specification — how MCP servers declare tools, how clients invoke them, and how results are returned.
Security and governance
OWASP AI Agent Security Cheat Sheet
OWASP’s practical security guidance for AI agents, covering prompt injection, tool abuse, data handling, and deployment controls.
OWASP Agentic Skills Top 10
The OWASP Top 10 for agentic skills — the most critical security risks to address when building and deploying agent skill systems.
NIST AI Risk Management Framework
The NIST AI RMF — a framework for identifying, measuring, managing, and governing AI risk across the full system lifecycle.