Tutorial 09: Custom Legal Skills, Hooks & Agents

Build custom skills for your firm's workflows, create compliance hooks, and deploy multi-agent systems for complex legal tasks.

What You'll Learn

This tutorial shows you how to build custom legal skills, add safety checks (hooks), and run multi-agent workflows. Some technical comfort is required.

Expert Level

Developer skills recommended. Estimated time: 120 minutes.

Learning Objectives

By the end of this tutorial, you will:

Understand Claude Code's architecture (Skills, Hooks, Sub-agents)
Build custom legal skills for your firm's workflows
Create hooks for quality control and compliance
Deploy multi-agent systems for complex legal tasks

Part 1: Understanding the Claude Code Stack

Architecture Overview

CLAUDE CODE STACK
│
├── SKILLS
│   └── Specialized instructions and best practices
│       stored in files Claude reads based on context
│
├── HOOKS
│   └── Scripts that run at specific points in
│       Claude's execution lifecycle
│
├── SUB-AGENTS
│   └── Autonomous agents spawned to handle
│       specific subtasks
│
├── MCP SERVERS
│   └── External tool connections (covered in Tutorial 07)
│
└── PLUGINS
    └── Packaged bundles of Skills + Hooks + MCP

Component	Legal Application
Skills	Encode playbooks, review procedures, drafting standards
Hooks	Enforce compliance, prevent unauthorized actions, audit logging
Sub-agents	Parallelize document review, research tasks
Plugins	Package firm workflows for distribution

Claude Code 2.1.133 adds worktree.baseRef, effort-level hook inputs, managed sandbox binary settings, and fixes for MCP OAuth proxy handling, concurrent-session auth, and subagent skill discovery. For legal automations, set the worktree base deliberately, retest hooks that depend on effort level or permissions, and rerun MCP-connected document workflows before production use.

Claude Code 2.1.139 update

Claude Code 2.1.139 adds agent view, /goal, direct hook argument execution with args, PostToolUse continuation with continueOnBlock, MCP CLAUDE_PROJECT_DIR environment support, and subagent telemetry headers. For legal workflows, retest privileged-folder hooks, MCP server configs, and goal-driven unattended sessions in a sandbox before using them on client or privileged material.

Part 2: Building Custom Legal Skills

What Are Skills?

Skills are specialized instructions stored in files that Claude reads based on context. Unlike prompts (one-time), Skills persist and activate automatically.

Skill File Structure

your-skill/
├── SKILL.md          # Main instructions (required)
├── examples/         # Example inputs/outputs
│   ├── good-review.md
│   └── bad-review.md
├── templates/        # Document templates
│   ├── nda-template.docx
│   └── redline-template.docx
└── resources/        # Reference materials
    ├── playbook.json
    └── clause-library.md

Creating a Contract Review Skill

Step 1: Create Skill Directory

mkdir -p ~/.claude/skills/contract-review
cd ~/.claude/skills/contract-review

Step 2: Write SKILL.md

# Contract Review Skill
 
## Purpose
This skill provides comprehensive contract review capabilities
aligned with [Firm Name]'s standard practices.
 
## Activation
Activate this skill when:
- User uploads a contract document
- User mentions "contract review" or similar
- User references specific contract types (NDA, MSA, SaaS, etc.)
 
## Process
 
### Step 1: Classification
Before analyzing, identify:
1. **Contract Type**: NDA, MSA, SaaS, License, Services, etc.
2. **Our Role**: Which party do we represent?
3. **Counterparty Profile**: Enterprise, mid-market, startup?
4. **Deal Tier**: Estimated value and strategic importance
 
### Step 2: Document Processing
- Read entire contract before providing analysis
- Note all defined terms and their definitions
- Identify governing law and dispute resolution
- Map clause structure and cross-references
 
### Step 3: Playbook Application
Apply positions from `resources/playbook.json`:
- Compare each clause to standard position
- Identify deviations and assess severity
- Note missing required provisions
 
### Step 4: Risk Assessment
For each issue:
- Assign severity: RED | YELLOW | GREEN
- Explain practical business impact
- Consider interaction with other clauses
 
### Step 5: Redline Generation
For RED and YELLOW issues:
- Provide specific alternative language
- Reference clause library when applicable
- Explain rationale for changes
 
### Step 6: Output Generation
Structure response as:
1. Executive Summary (3-5 sentences)
2. Deal Parameters Table
3. Clause-by-Clause Analysis
4. Risk Score and Escalation Recommendation
5. Negotiation Priorities
6. Questions for Business Team
 
## Clause Library
Reference `resources/clause-library.md` for approved language.
 
## Examples
See `examples/` directory for good and bad review examples.
 
## Calibration Notes
- Liability cap thresholds updated January 2026
- New data processing requirements per GDPR changes
- Updated AI/ML clause language required
 
## Quality Requirements
- Never provide legal advice without qualification
- Flag any clause requiring jurisdictional verification
- Note when playbook doesn't cover specific terms
- Recommend escalation for deals over $500K

Step 3: Create Playbook Resource

resources/playbook.json:

{
  "contract_types": {
    "SaaS_Customer": {
      "liability": {
        "standard": "12 months fees",
        "minimum": "total contract value",
        "carve_outs": ["indemnification", "data_breach", "confidentiality", "IP", "gross_negligence", "willful_misconduct"]
      },
      "indemnification": {
        "required_vendor": ["IP_infringement", "data_breach", "security_failure"],
        "acceptable_exclusions": ["customer_modifications", "third_party_components_with_notice"]
      },
      "data": {
        "ownership": "customer",
        "vendor_rights": "service_delivery_only",
        "prohibited_uses": ["AI_training", "analytics", "marketing", "sale"],
        "retention_limit": "30_days_post_termination"
      }
    }
  },
  "severity_matrix": {
    "RED": [
      "unlimited_customer_liability",
      "no_vendor_indemnity",
      "data_used_for_AI_training",
      "no_termination_for_convenience"
    ],
    "YELLOW": [
      "liability_cap_below_12_months",
      "narrow_indemnity_carveouts",
      "60_plus_day_termination_notice"
    ]
  }
}

Step 4: Create Clause Library

resources/clause-library.md:

# Approved Clause Language Library
 
## Limitation of Liability
 
### Standard Mutual Cap
"EACH PARTY'S TOTAL LIABILITY ARISING OUT OF OR RELATED TO THIS
AGREEMENT SHALL NOT EXCEED THE FEES PAID OR PAYABLE BY CUSTOMER
IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM."
 
### Uncapped Carve-Outs Addition
"THE FOREGOING LIMITATION SHALL NOT APPLY TO: (A) EITHER PARTY'S
INDEMNIFICATION OBLIGATIONS; (B) BREACH OF SECTION [DATA SECURITY];
(C) BREACH OF CONFIDENTIALITY OBLIGATIONS; (D) EITHER PARTY'S
GROSS NEGLIGENCE OR WILLFUL MISCONDUCT; OR (E) CUSTOMER'S PAYMENT
OBLIGATIONS."
 
## Data Ownership
 
### Customer Ownership Clause
"As between the parties, Customer retains all right, title, and
interest in and to Customer Data. Vendor acquires no rights in
Customer Data except the limited license granted herein."
 
### No AI Training Clause
"Vendor shall not use Customer Data or any derivatives thereof
to train, develop, or improve any machine learning model,
artificial intelligence system, or similar technology."
 
[Continue with additional clauses...]

Step 5: Install and Test

# Skills in Claude Code are discovered from filesystem locations:
# - ~/.claude/skills/ (personal)
# - .claude/skills/ (project)
#
# Restart Claude Code (or start a new session), then test:
claude "I need to review a software agreement"
# Claude should load and apply the skill

Part 3: Building Compliance Hooks

What Are Hooks?

Hooks are scripts that execute at specific points in Claude's operation:

Production note: Hooks can block or alter a workflow. Test them in a sandbox with the real permissions, effort levels, and MCP servers before using them on client matters or privileged documents.

Claude Code 2.1.139 adds an exec-form hook args field and continueOnBlock for PostToolUse. Prefer exec-form arguments for hooks that receive file paths or matter identifiers because they avoid shell quoting issues. Use continueOnBlock only when the hook's rejection reason is safe to feed back into the model and does not reveal privileged or confidential facts.

Hook Type	Trigger Point	Use Case
`PreToolUse`	Before any tool runs	Block dangerous actions
`PostToolUse`	After tool completes	Audit logging
`SessionStart`	When session begins	Load context
`UserPromptSubmit`	Before prompt processing	Filter content
`Stop`	When Claude finishes responding	Quality checks

Claude Code 2.1.141 hook updates

Claude Code 2.1.141 adds a terminalSequence field to hook JSON output for desktop notifications, window titles, and bells without a controlling terminal. It also fixes hook transcript paths after EnterWorktree changes the working directory. For legal workflows, keep hook output limited to non-confidential status signals, retest transcript-path assumptions, and avoid putting matter names or privileged facts into terminal titles or notifications.

Legal Compliance Hook Example

Purpose: Prevent Claude from making unauthorized changes to privileged documents.

Step 1: Create Hook Directory

mkdir -p ~/.claude/hooks

Step 2: Create Hook Scripts

~/.claude/hooks/pretool-privileged-guard.sh:

#!/usr/bin/env bash
set -euo pipefail
 
input="$(cat)"
tool_name="$(jq -r '.tool_name // ""' <<<"$input")"
path_value="$(jq -r '.tool_input.file_path // .tool_input.path // ""' <<<"$input")"
 
if [[ "$tool_name" =~ ^(Read|Write|Edit)$ ]] && \
   ([[ "$path_value" == *"/Privileged/"* ]] || [[ "$path_value" == *"/Attorney-Client/"* ]]); then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Privileged folder access requires explicit user approval."
    }
  }'
  exit 0
fi
 
exit 0

~/.claude/hooks/posttool-audit-log.sh:

#!/usr/bin/env bash
set -euo pipefail
 
mkdir -p "$HOME/.claude/logs"
input="$(cat)"
echo "$input" >> "$HOME/.claude/logs/legal-hooks-audit.jsonl"
exit 0

Step 3: Configure Hook

~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/hooks/pretool-privileged-guard.sh\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/hooks/posttool-audit-log.sh\""
          }
        ]
      }
    ]
  }
}

Additional Hook Use Cases

Citation Verification Hook (Stop):

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/hooks/stop-citation-warning.sh\""
          }
        ]
      }
    ]
  }
}

Confidentiality Check Hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "WebSearch|WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/hooks/pretool-confidentiality-check.sh\""
          }
        ]
      }
    ]
  }
}

Part 4: Multi-Agent Legal Workflows

Understanding Sub-Agents

Claude can spawn sub-agents to handle specific tasks:

Parallelization: Multiple documents reviewed simultaneously
Specialization: Different agents for different tasks
Isolation: Separate context for separate analyses

Claude Code 2.1.141 adds claude agents --cwd <path> to scope the session list to a directory, and background agents launched with /bg or ←← now preserve the current permission mode. Use the directory scope when auditing agents tied to a matter workspace, and verify background sessions keep the intended permission posture before assigning privileged-document or repository-writing tasks.

Example: Parallel Due Diligence Review

// Due Diligence Multi-Agent Workflow
 
const agents = [
  {
    name: 'contract-reviewer',
    task: 'Review all customer agreements',
    folder: '/DD/Contracts/Customers',
    instructions: 'Apply customer agreement playbook'
  },
  {
    name: 'ip-reviewer',
    task: 'Review all IP agreements',
    folder: '/DD/Contracts/IP',
    instructions: 'Apply IP agreement playbook'
  },
  {
    name: 'employment-reviewer',
    task: 'Review all employment agreements',
    folder: '/DD/Contracts/Employment',
    instructions: 'Apply employment agreement playbook'
  },
  {
    name: 'litigation-reviewer',
    task: 'Analyze all pending litigation',
    folder: '/DD/Litigation',
    instructions: 'Assess litigation exposure and reserves'
  }
];
 
// Spawn all agents in parallel
const results = await Promise.all(
  agents.map(agent =>
    claude.spawnAgent({
      name: agent.name,
      prompt: `${agent.task} in ${agent.folder}. ${agent.instructions}.
               Output findings in structured JSON format.`,
      timeout: 30 * 60 * 1000 // 30 minute timeout
    })
  )
);
 
// Synthesize results
const synthesis = await claude.prompt(`
  I've received due diligence findings from ${agents.length} specialized reviewers.
 
  ${results.map((r, i) => `
  ## ${agents[i].name} Findings:
  ${r.output}
  `).join('\n')}
 
  Please synthesize into:
  1. Executive Summary of DD findings
  2. Critical issues requiring immediate attention
  3. Risk matrix by category
  4. Recommended deal adjustments
  5. Items requiring seller disclosure
`);

Example: Research + Draft Workflow

// Legal Research + Drafting Multi-Agent Workflow
 
async function researchAndDraft(topic, jurisdiction, outputType) {
  // Stage 1: Research Agent
  const research = await claude.spawnAgent({
    name: 'legal-researcher',
    prompt: `Research ${topic} under ${jurisdiction} law.
             Use available legal research tools (Midpage, CourtListener).
             Provide comprehensive analysis with citations.
             Format as structured legal memorandum outline.`,
    tools: ['midpage', 'courtlistener', 'webSearch']
  });
 
  // Stage 2: Draft Agent (uses research output)
  const draft = await claude.spawnAgent({
    name: 'legal-drafter',
    prompt: `Based on this research:
             ${research.output}
 
             Draft a ${outputType} addressing ${topic}.
             Include all relevant citations.
             Follow firm style guide.`,
    context: research.output
  });
 
  // Stage 3: Review Agent
  const review = await claude.spawnAgent({
    name: 'quality-reviewer',
    prompt: `Review this draft for:
             1. Legal accuracy
             2. Citation completeness
             3. Style compliance
             4. Missing analysis
 
             Draft:
             ${draft.output}`,
    context: draft.output
  });
 
  return {
    research: research.output,
    draft: draft.output,
    review: review.output
  };
}

Part 5: Packaging Skills into Plugins

Plugin Structure

legal-contract-plugin/
├── plugin.json           # Plugin manifest
├── SKILL.md             # Main skill
├── .mcp.json            # MCP server config
├── hooks/
│   └── compliance.js    # Compliance hooks
├── commands/
│   └── review.md        # Slash command definitions
├── resources/
│   ├── playbook.json
│   └── clauses.md
└── README.md

Plugin Manifest

Plugin metadata and schema evolve quickly. Use the official plugins reference for the current manifest format, then map your legal assets into that structure.

Minimal hooks/hooks.json example:

{
  "description": "Legal compliance checks",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pretool-privileged-guard.sh"
          }
        ]
      }
    ]
  }
}

Installing and Distributing

# Local development (session-scoped)
claude --plugin-dir /absolute/path/to/legal-contract-plugin
 
# Marketplace install (recommended for team rollout)
claude plugin install legal-contract-review@your-marketplace --scope project
 
# Lifecycle operations
claude plugin enable legal-contract-review@your-marketplace --scope project
claude plugin update legal-contract-review@your-marketplace --scope project

For environments without a GitHub SSH key, Claude Code 2.1.141 adds CLAUDE_CODE_PLUGIN_PREFER_HTTPS so GitHub plugin sources can be cloned over HTTPS. Enterprise teams using workload identity federation can also set ANTHROPIC_WORKSPACE_ID to scope minted tokens to a specific workspace when the federation rule covers more than one workspace.

Part 6: Security Considerations

Skill Security

Source verification: Only install skills from trusted sources
Code review: Review all hook code before deployment
No client data: Never include client data in skill files
Version control: Track changes to skills
Access control: Limit who can modify firm skills

Data Protection

// Example: UserPromptSubmit sanitization hook (conceptual)
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME/.claude/hooks/userprompt-sanitize.sh\""
          }
        ]
      }
    ]
  }
}

Compliance Requirements

Skills reviewed by IT security
Hooks tested in sandbox environment
Audit logging enabled
Client data segregation verified
Access controls configured
Backup procedures documented

Do This Now

Create a custom skill for one of your firm's review processes
Add at least one safety check (hook) for compliance or audit logging
Test a multi-agent workflow for parallel document processing
Document your skill so your team can use it
Consider packaging as a plugin for distribution

Quick Reference: Claude Code Commands

# Skills (filesystem locations)
~/.claude/skills/           # Personal custom skills
.claude/skills/             # Project custom skills
 
# Hooks
/hooks                      # Open hooks manager in Claude Code
 
# Plugin hooks
${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json
 
# Debugging
claude --help