Deep Agents Day 9: Skills and HITL for Enforcing Team Rules with Human Approval

Skills and interrupt_on overview

Deep Agents separates two capabilities: skills encode professional rules and team conventions, while interrupt_on enables human‑in‑the‑loop (HITL) approval for high‑risk tool calls. Neither mechanism provides automatic safety; the ultimate safety boundary relies on permissions, sandboxing, audit logs, and overall team processes.

Defining skills

In deepagents==0.5.3 the create_deep_agent function expects a list of skill‑source paths, not a Python dict. Example:

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(
    root_dir="./agent-data",
    virtual_mode=True,
)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    skills=["/skills/project/"],
)

Each skill is a folder under the specified backend path and must contain a SKILL.md file.

Typical skill directory layout:

/skills/project/code-review/
├── SKILL.md
└── checklist.md

SKILL.md

uses YAML front‑matter to declare metadata:

---
name: code-review
description: Review Python code for correctness, maintainability, tests, and security risks.
license: MIT
---

# Code Review

Use this skill when the user asks for code review.

Focus on:
- correctness bugs
- missing tests
- security issues
- maintainability risks

Key rules for skills: name should match the directory name (e.g., code-review). description is critical because the model uses it to decide when to invoke the skill.

Later definitions of a skill with the same name override earlier ones; path order matters.

Skill files are read through the Deep Agents backend and must not bypass its filesystem abstraction.

When to create a skill

A skill is appropriate for content that is stable and reusable. Examples of suitable content include:

Code‑review standards

Security‑scan checklists

Documentation templates

SQL audit rules

API compatibility checklists

Team release checklists

Unsuitable content includes one‑off task descriptions, personal values, API keys, passwords, or any rule that must be enforced by permissions rather than by a skill.

Value of a code‑review skill

Defining a code-review skill enforces a consistent checklist:

Correctness bugs

Boundary conditions

Test coverage

Security risks

Maintainability

Output format

This guarantees a stable review structure; without a skill the model may produce inconsistent or vague summaries.

Human‑in‑the‑Loop (HITL) configuration

The interrupt_on parameter activates HITL. A minimal configuration:

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    interrupt_on={
        "edit_file": True,
        "execute": True,
    },
    checkpointer=True,
)

When the agent attempts to call edit_file or execute, execution pauses, the tool name and parameters are presented to an external UI, and a human can approve, edit, or reject.

A more detailed configuration uses InterruptOnConfig:

from langchain.agents.middleware import InterruptOnConfig

interrupt_on = {
    "execute": InterruptOnConfig(
        allowed_decisions=["approve", "edit", "reject"],
        description="Human must confirm before executing a shell command.",
    ),
    "write_file": True,
}

Note: delete_file should not be added because the current file tools do not expose that name; deletion is handled via execute with appropriate risk handling.

Approval flow execution

Agent decides to call a tool
 → HumanInTheLoopMiddleware matches interrupt_on
 → Graph pauses and returns interrupt info
 → CLI/Web/API displays tool name and arguments
 → Human chooses approve / edit / reject
 → Graph restores from checkpoint and continues

A checkpointer must be configured; otherwise the approval state cannot survive across requests.

Four mechanisms and their responsibilities

skills

: encode professional procedures and team conventions. interrupt_on: pause execution for high‑risk tool calls. permissions: restrict which file paths tools may read or write.

sandbox: isolate command execution and side effects.

Example composition

security-audit

skill defines a security‑checklist. permissions allow read‑only access to /workspace/src/**. edit_file triggers HITL before fixing a vulnerability. execute runs tests inside a remote sandbox.

All tool calls and approval outcomes are logged.

This combination yields an agent that can operate within a team’s process while respecting safety boundaries.