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

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"

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

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

undefined

You should see `SKILL.md`, `README.md`, `icon.jpeg`, and `references/`.

---

agents-best-practices/
├── SKILL.md                                  # skill entrypoint (this file)
├── README.md                                 # public-facing overview
├── icon.jpeg                                 # skill icon
└── references/
    ├── mvp-agent-blueprint.md                # MVP harness generator
    ├── architecture.md                       # component model
    ├── agentic-loop.md                       # loop invariants and budgets
    ├── tools-and-permissions.md              # typed tools and risk classes
    ├── planning-and-goals.md                 # planning mode and long-running goals
    ├── context-memory-compaction.md          # context, memory, retrieval
    ├── prompt-caching-and-cost.md            # cache-aware context layout
    ├── skills-and-connectors.md              # Agent Skills, MCP, connectors
    ├── system-prompts-instructions.md        # instruction hierarchy
    ├── provider-api-patterns.md              # OpenAI, Anthropic, compatible APIs
    ├── security-evals-observability.md       # guardrails, tracing, evals
    ├── agent-legibility-feedback-loops.md    # artifacts and cleanup
    ├── checklists.md                         # implementation and audit checklists
    ├── coverage-audit.md                     # topic coverage verification
    └── source-links.md                       # official references

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

// Good: Narrow, typed, deterministic
interface SendCustomerEmailTool {
  name: "send_customer_email";
  parameters: {
    account_id: string;
    template: "renewal_reminder" | "upgrade_offer" | "support_followup";
    variables: Record<string, string>;
  };
  permission: "approval_gate";
}

// Bad: Generic, untyped, unbounded
interface SendMessageTool {
  name: "send_message";
  parameters: {
    to: string;
    body: string;
  };
}

interface PlanningResult {
  plan: string;              // What the agent intends to do
  required_approvals: string[];  // Tools needing human approval
  estimated_steps: number;
  estimated_cost_usd: number;
  risk_summary: string;
}

// User approves the plan, then agent executes

interface AgentContext {
  // Stable, cache-friendly prefix
  system_instructions: string;
  skill_descriptions: string[];
  
  // Active state (outside prompt)
  plan: Plan | null;
  pending_approvals: Approval[];
  todos: Todo[];
  artifacts: Artifact[];
  
  // Recent conversation (compacted)
  messages: Message[];
  
  // Retrieved knowledge
  retrieved_docs: Document[];
}

// Stable prefix (cached)
const systemPrefix = [
  systemInstructions,
  allSkillDescriptions,
  allToolSchemas,
  permanentExamples
];

// Dynamic suffix (not cached)
const dynamicSuffix = [
  retrievedDocs,
  recentMessages,
  currentTask
];

// OpenAI: system, cached_user, user
// Anthropic: system (cached), user (cached), user

interface ModelCallTelemetry {
  input_tokens: number;
  output_tokens: number;
  cached_tokens: number;
  cost_usd: number;
  cache_hit_rate: number;
}

// Step 1: Load skill summaries (cached)
const skillIndex = [
  { name: "web-search", description: "Search the web..." },
  { name: "code-analysis", description: "Analyze codebases..." }
];

// Step 2: Load full skill when relevant
if (userNeedsWebSearch) {
  const webSearchSkill = loadSkill("web-search");
  context.push(webSearchSkill.fullInstructions);
}

// Expose MCP server as typed tools
const mcpTools = await mcpClient.listTools();
for (const tool of mcpTools) {
  registerTool({
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema,
    permission: classifyRisk(tool.name)
  });
}

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

undefined

Reference: `references/mvp-agent-blueprint.md`

---

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

undefined

References: `references/agentic-loop.md`, `references/context-memory-compaction.md`, `references/security-evals-observability.md`

---

The ops agent needs Slack, Linear, Google Drive, and our internal deploy API.
How should tools and permissions work?

undefined

// Good: Narrow, typed
interface PostSlackMessageTool {
  name: "post_slack_message";
  parameters: {
    channel: string;  // Must match allow-list
    message: string;
    thread_ts?: string;
  };
  permission: "approval_gate";
}

// Bad: Generic, unbounded
interface SendMessageTool {
  name: "send_message";
  parameters: {
    platform: string;
    destination: string;
    content: string;
  };
}

// Agent proposes
const proposal = {
  tool: "post_slack_message",
  args: { channel: "#incidents", message: "Deploy complete." },
  rationale: "Notify team of successful rollout."
};

// Harness pauses and stores
const approval = await requestApproval(proposal);

// Human reviews in UI
// On approval, harness executes and returns observation
const result = await executeWithApproval(approval.id);

// Wrap external APIs as typed tools
class SlackConnector {
  async postMessage(channel: string, message: string): Promise<ToolResult> {
    // Validate channel against allow-list
    if (!this.allowedChannels.includes(channel)) {
      return { status: "denied", reason: "Channel not in allow-list" };
    }
    
    // Execute
    const response = await this.slackClient.chat.postMessage({
      channel,
      text: message
    });
    
    // Return structured observation
    return {
      status: "success",
      data: { ts: response.ts, channel: response.channel },
      metadata: { timestamp: Date.now(), cost_usd: 0 }
    };
  }
}

What should I check before launching this agent?

undefined

Reference: `references/checklists.md`, `references/security-evals-observability.md`

---

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: systemInstructions },
    { role: "user", content: task }
  ],
  tools: tools.map(t => ({
    type: "function",
    function: {
      name: t.name,
      description: t.description,
      parameters: t.parameters
    }
  })),
  tool_choice: "auto"
});

// Handle tool calls
if (response.choices[0].message.tool_calls) {
  for (const toolCall of response.choices[0].message.tool_calls) {
    const result = await executeToolWithPermission(
      toolCall.function.name,
      JSON.parse(toolCall.function.arguments)
    );
    
    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify(result)
    });
  }
}

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const response = await client.messages.create({
  model: "claude-3-7-sonnet-20250219",
  max_tokens: 4096,
  system: [
    { type: "text", text: systemInstructions, cache_control: { type: "ephemeral" } }
  ],
  messages: [
    { role: "user", content: task }
  ],
  tools: tools.map(t => ({
    name: t.name,
    description: t.description,
    input_schema: t.parameters
  }))
});

// Handle tool calls
if (response.stop_reason === "tool_use") {
  for (const block of response.content) {
    if (block.type === "tool_use") {
      const result = await executeToolWithPermission(block.name, block.input);
      
      messages.push({
        role: "user",
        content: [{
          type: "tool_result",
          tool_use_id: block.id,
          content: JSON.stringify(result)
        }]
      });
    }
  }
}

// Track cache metrics
console.log({
  input_tokens: response.usage.input_tokens,
  cache_read_tokens: response.usage.cache_read_input_tokens,
  cache_creation_tokens: response.usage.cache_creation_input_tokens
});

interface AgentConfig {
  model: {
    provider: "openai" | "anthropic" | "openai-compatible";
    model: string;
    base_url?: string;
    api_key_env: string;
  };
  
  loop: {
    max_steps: number;           // e.g., 30
    timeout_seconds: number;     // e.g., 300
    max_cost_usd: number;        // e.g., 1.0
    max_tool_calls_per_step: number;  // e.g., 5
  };
  
  context: {
    max_messages: number;        // e.g., 50
    compaction_threshold: number; // e.g., 40
    max_tool_result_bytes: number; // e.g., 4096
  };
  
  permissions: {
    auto_approve: string[];      // e.g., ["read_private_data", "draft_external_message"]
    require_approval: string[];  // e.g., ["external_communication", "destructive_action"]
  };
  
  observability: {
    trace_enabled: boolean;
    cost_tracking_enabled: boolean;
    eval_mode: "shadow" | "production";
  };
}

const config: AgentConfig = {
  model: {
    provider: "anthropic",
    model: "claude-3-7-sonnet-20250219",
    api_key_env: "ANTHROPIC_API_KEY"
  },
  loop: {
    max_steps: 30,
    timeout_seconds: 300,
    max_cost_usd: 1.0,
    max_tool_calls_per_step: 5
  },
  context: {
    max_messages: 50,
    compaction_threshold: 40,
    max_tool_result_bytes: 4096
  },
  permissions: {
    auto_approve: ["read_private_data", "draft_external_message"],
    require_approval: ["external_communication", "write_database", "destructive_action"]
  },
  observability: {
    trace_enabled: true,
    cost_tracking_enabled: true,
    eval_mode: "shadow"
  }
};

// Add hard budgets
if (step >= config.loop.max_steps) {
  return { status: "budget_exhausted", reason: "max_steps" };
}

if (Date.now() - startTime > config.loop.timeout_seconds * 1000) {
  return { status: "timeout", reason: "time_budget" };
}

// Add stop rules
if (allTodosComplete() || userAborted() || criticalError()) {
  return { status: "terminated", reason: ... };
}

interface ActiveState {
  plan: Plan | null;
  pending_approvals: Approval[];
  todos: Todo[];
  artifacts: Artifact[];
}

// Store outside prompt
const state = loadState(taskId);

// Rehydrate after compaction
const context = buildContext({
  system: systemInstructions,
  plan: state.plan,
  todos: state.todos,
  messages: compactedMessages
});

async function executeToolWithPermission(tool: string, args: any): Promise<ToolResult> {
  const permission = getToolPermission(tool);
  
  if (permission === "approval_gate") {
    const approval = await findApproval(tool, args);
    if (!approval || approval.status !== "approved") {
      return { status: "denied", reason: "Requires human approval" };
    }
  }
  
  // Execute only after permission check passes
  return await executeTool(tool, args);
}

// OpenAI: Use system + cached_user pattern
const messages = [
  { role: "system", content: stablePrefix },
  { role: "user", content: cachedKnowledge, cache_control: { type: "ephemeral" } },
  { role: "user", content: dynamicTask }
];

// Anthropic: Cache system blocks
const system = [
  { type: "text", text: stablePrefix, cache_control: { type: "ephemeral" } }
];

// Track cache hit rate
if (cacheHitRate < 0.7) {
  console.warn("Low cache hit rate; review context layout");
}

// Label trust boundaries
const messages = [
  { role: "user", content: userInput, metadata: { source: "user", trusted: false } },
  { role: "assistant", content: modelOutput, metadata: { source: "model" } },
  { role: "tool", content: toolResult, metadata: { source: "tool", trusted: true } }
];

// Validate tool arguments against schema
const valid = validateSchema(tool.parameters, args);
if (!valid) {
  return { status: "validation_failed", errors: valid.errors };
}

// Run injection evals
await runEval("prompt_injection", testCases);