Skills vs Agents: Architecture Comparison

Quick Decision Matrix

Core Architectural Principles

How Skills Actually Work (Automatic Context Injection)

Skills provide automatic context management out-of-the-box:

1. Discovery Phase (Conversation Start, ~30-50 tokens/skill)

   • Claude scans .claude/skills/ (project) and ~/.claude/skills/ (personal)
   • Reads YAML frontmatter from each SKILL.md
   • Loads: name + description into catalog
   • Result: Claude knows what capabilities exist

2. Semantic Matching (Request Analysis, ~0 tokens)

   • User request: "Review authentication code"
   • Claude compares request against skill descriptions
   • Pattern matching: "authentication" → authentication-security skill
   • Decision: Activate matched skill

3. Context Injection (Dynamic Loading, skill-dependent tokens)

   • Claude reads full SKILL.md content
   • Loads instructions, rules, guidelines
   • Additional files (rules.json) loaded on-demand
   • Context: User request + Skill instructions

4. Application (Response Generation)

   • Claude applies skill knowledge to user request
   • Follows security rules from loaded skill
   • Returns analysis per skill structure

Key insight: Skills automatically activate via semantic matching - no manual invocation needed.

Skills are Useful For:

• Automatic context activation based on request content
• Interactive workflows where Claude decides what knowledge to apply
• Progressive disclosure (load descriptions first, content on-match)
• Token efficiency (small discovery cost, larger on activation)
• Zero cognitive load (no need to remember which skill to call)

Agents are Better For:

• Explicit parallel execution (multiple sub-agents via Agent SDK)
• Programmatic invocation (CI/CD, pre-commit hooks, automated pipelines)
• Background execution with monitoring and output retrieval
• Deterministic workflows (user controls exactly which agents run)
• Orchestration patterns (main agent delegates to specialist sub-agents)

Rule of Thumb: Skills and agents are complementary, not competing. Use skills for automatic context injection in interactive workflows. Use agents for explicit parallel execution in programmatic workflows.

How Skills Solve Automatic Context Management

Skills already provide intelligent, automatic context injection:

Real-World Example: Authentication Review

With Agents (Manual):

// User: "Fix authentication vulnerability in src/auth/login.py"
// Developer must explicitly invoke:
use authentication-specialist agent to review src/auth/login.py
// Problem: Developer must know which agent to call

With Skills (Automatic):

// User: "Fix authentication vulnerability in src/auth/login.py"
// Claude automatically:
1. Matches "authentication vulnerability" → authentication-security skill
2. Loads authentication-security/SKILL.md (~2-5k tokens)
3. Applies 45 authentication rules during analysis
4. Returns security-aware recommendations
// Benefit: Zero manual invocation, Claude decides what knowledge to apply

How Semantic Matching Works

The description field is the activation trigger:

# authentication-security/SKILL.md
---
name: authentication-security
description: Authentication security expertise covering login mechanisms,
  MFA, password policies, and credential management based on 45+ ASVS-aligned
  security rules
---

Semantic matching examples:

• User: "Review this login code" → Match: "login mechanisms"
• User: "Check password hashing" → Match: "password policies"
• User: "Validate MFA implementation" → Match: "MFA"
• User: "Analyze authentication flow" → Match: "Authentication security"

Claude autonomously activates the skill when request semantically matches description.

Progressive Disclosure in Action

How skills achieve token efficiency:

Session Start (All Skills)
├─ authentication-security: small cost (name + description)
├─ session-management-security: small cost
├─ secrets-management: small cost
├─ [... 12 more skills]: minimal per-skill cost
└─ Total Discovery Cost: modest upfront investment

User Request: "Review authentication code"
├─ Semantic Match: authentication-security skill
├─ Load Full Skill: authentication-security/SKILL.md (moderate cost)
├─ On-Demand: Load rules.json if needed (larger cost)
└─ Total Cost: discovery + skill content + (optional rules)

Compare to Agents (Manual Invocation)
├─ No discovery phase (user must know agent exists)
├─ Load Full Agent: authentication-specialist.md (moderate cost)
├─ Load Rules: json/authentication-specialist.json (large cost)
└─ Total Cost: all context loaded upfront, no progressive loading

Skills advantage: Only load full content when semantically matched to request.

Multi-Skill Composition

Skills can auto-activate together for complex requests:

// User: "Implement secure JWT authentication with environment-based secrets"

// Claude automatically activates:
1. authentication-security skill → "authentication" match
2. session-management-security skill → "JWT" match
3. secrets-management skill → "secrets" match

// Result: 3 skills loaded, all relevant knowledge applied
// Cost: discovery overhead + content for each activated skill
// Compare to: Manually invoking multiple agents via Agent SDK

Key Takeaway: Skills automatically solve the context management problem through semantic matching and progressive disclosure. No additional infrastructure needed.

Architecture Comparison

Agents (Current, .claude/agents/*.md)

Purpose: Task execution via Claude Code Task system

Structure:

---
name: authentication-specialist
description: Brief description
tools: Read, Grep, Bash
---

[All instructions and context loaded upfront]

Invocation:

use the authentication-specialist agent to analyze src/auth/login.py

Characteristics:

• ✅ Parallel Execution: Multiple sub-agents run simultaneously
• ✅ Programmatic: Explicit invocation via Agent SDK
• ✅ Fast: Optimized for automated execution
• ✅ Validated: Existing workflow, proven in production
• ✅ On-Demand Loading: References JSON rule files, loads when needed
• ✅ Composition: comprehensive-security-agent includes all specialist rules
• ⚠️ Less discoverable: Harder to understand capabilities without reading agent files

Token Usage:

Initial load: moderate (agent instructions + frontmatter)
On-demand: Load JSON rule file when needed (larger cost)
Total: varies depending on whether rules are loaded

Best For:

• Automated security validation
• CI/CD integration
• Parallel security scanning
• Pre-commit hooks
• Programmatic invocation

Skills (New, .claude/skills/*/SKILL.md)

Purpose: Progressive context loading and skill composition

Structure:

# .claude/skills/authentication-security/SKILL.md
---
name: authentication-security
description: Detailed description
version: 1.0.0
domains: [user-authentication, mfa, passwords]
tools: Read, Grep, Bash
---

# Authentication Security Skill

## Skill Capabilities
[Overview - loads first]

## Usage Patterns
[When to use - loads second]

## Examples
[Code samples - loads on demand]

## Integration
[Composition with other skills - loads on demand]

Invocation:

Activate authentication-security skill and analyze src/auth/login.py

Characteristics:

• ✅ Progressive Disclosure: Load context incrementally
• ✅ Discoverable: Clear capabilities and usage patterns
• ✅ Composable: Skills reference and build on each other
• ✅ Rich Examples: Concrete code snippets included
• ✅ Human-Readable: Designed for understanding
• ✅ Automatic Activation: Semantic matching on description
• ✅ Token Efficient: Small cost until activated

Token Usage:

Initial load: small (name + description during discovery)
On-activation: moderate (full SKILL.md content)
On-demand: larger (full rules via JSON symlink if needed)
Total if all loaded: varies based on what's needed
Advantage: Can provide guidance without loading full rule set

Best For:

• Interactive security guidance
• Learning secure coding patterns
• Multi-domain security analysis
• Understanding security capabilities
• Composing security workflows
• Automatic context injection

Hybrid Architecture (Current Implementation)

We use BOTH skills and agents in a two-layer architecture:

.claude/
├── skills/              # Skills layer: Auto-Discovery + Progressive Loading
│   └── authentication-security/
│       ├── SKILL.md                    # Progressive disclosure entry point
│       ├── rules.json                  # Symlink to agent JSON
│       └── examples/                   # Code examples (future)
│
└── agents/              # Agents layer: Explicit Execution + Parallelism
    ├── authentication-specialist.md    # Task execution
    └── json/
        └── authentication-specialist.json  # Compiled rules

Layer Interaction

Scenario 1: Interactive Learning (Skills)

User: "What are your authentication security capabilities?"

Claude: [Automatically activates authentication-security skill]
→ Progressive disclosure: Overview → Capabilities → Examples
→ Token-efficient: Only loads what's needed (~5k tokens)

Scenario 2: Automated Validation (Agents)

Pre-commit hook: Validate authentication changes

Task System: [Explicitly invokes authentication-specialist agent]
→ Fast: Loads full context immediately
→ Parallel: Runs with other agents simultaneously
→ Programmatic: No semantic matching needed

Scenario 3: Comprehensive Analysis (Hybrid)

User: "Review authentication system comprehensively"

Claude: [Automatically activates multiple skills]
1. authentication-security skill → Login mechanisms
2. session-security skill → Session handling
3. secrets-management skill → Credential storage

[Skills provide context, then Claude can optionally invoke parallel agents]
→ authentication-specialist agent
→ session-management-specialist agent
→ secrets-specialist agent

[Synthesizes results from all three]

When to Use Each Approach

Use Skills When:

1. Interactive Workflows

   • User doesn't know which capability they need
   • Claude should auto-detect relevant security domains
   • Progressive learning and exploration
   • Token efficiency is important

2. Automatic Context Injection

   • Semantic matching on user requests
   • Multi-skill composition for complex requests
   • Zero manual invocation needed

3. Discovery and Learning

   • Understanding security capabilities
   • Exploring secure coding patterns
   • Getting examples and guidance

Use Agents When:

1. Programmatic Invocation

   • CI/CD security scanning
   • Pre-commit validation hooks
   • Scheduled security audits
   • Explicit control over which agents run

2. Parallel Execution Required

   • Multi-domain security analysis
   • Comprehensive codebase scans
   • Time-sensitive validations
   • Background execution with monitoring

3. Deterministic Workflows

   • User knows exactly which security domain to check
   • Orchestration patterns (main agent delegates to specialists)
   • Integration with external tools

Use Hybrid (Skills + Agents) When:

1. Best of Both Worlds

   • Skills for automatic discovery and context
   • Agents for explicit parallel execution
   • Combined for complete workflow

2. Complex Security Reviews

   • Skills provide initial context and composition
   • Agents execute deep parallel analysis
   • Synthesis with skill-guided interpretation

Key Insights

1. Skills solve automatic context management - Semantic matching and progressive disclosure built-in
2. Agents solve explicit parallel execution - Agent SDK enables deterministic workflows
3. Both share rule knowledge - Symlinks ensure single source of truth
4. Complementary, not competing - Use the right tool for each scenario
5. No additional infrastructure needed - Skills already provide intelligent context injection

Defense-in-Depth Strategy: Skills + Hooks + Agents

Critical Understanding: Skills Are NOT Guaranteed

Skills activation is probabilistic, not deterministic:

From the official documentation:

"Skills are model-invoked—Claude autonomously decides when to use them based on your request and the Skill's description."

What this means for security:

• ✅ Skills may activate if description semantically matches request
• ❌ Skills may not activate if Claude doesn't recognize the match
• ❌ Cannot rely on skills alone for mandatory security enforcement

Example risk:

User: "Fix this authentication bug"
→ MIGHT activate authentication-security skill (probabilistic)
→ MIGHT NOT activate if semantic matching fails
→ Security guidance may be missed

The Solution: Three-Layer Security Architecture

Use skills, hooks, AND agents for comprehensive protection:

┌─────────────────────────────────────────────────────────┐
│ Layer 1: Skills (Proactive Guidance - Best Effort)     │
│ - Auto-activate based on semantic matching              │
│ - Guide Claude toward secure implementations            │
│ - Reliability: Probabilistic (not guaranteed)           │
│ - Purpose: Reduce violations before they happen         │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 2: Hooks (Mandatory Validation - Guaranteed)     │
│ - PreToolUse hooks execute before commits/writes        │
│ - Validate ALL code against security rules              │
│ - Reliability: 100% (deterministic execution)           │
│ - Purpose: Block unsafe operations, provide feedback    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│ Layer 3: Agents (Deep Analysis - On-Demand)            │
│ - Triggered by hooks when violations detected           │
│ - Explicit parallel security scanning                   │
│ - Comprehensive rule validation                         │
│ - Purpose: Generate detailed remediation guidance       │
└─────────────────────────────────────────────────────────┘

Complete Security Flow Example

Scenario: Add JWT authentication to API

// ============================================================
// STEP 1: User Starts Task
// ============================================================
User: "Add JWT authentication to the API"

// ============================================================
// STEP 2: Skills Activate (Proactive - Probabilistic)
// ============================================================
Claude scans skill descriptions:
→ authentication-security skill may activate
  ├─ Matches: "authentication" in request
  ├─ Loads: Password hashing, MFA, credential guidelines
  └─ Suggests: bcrypt, secure session handling

→ session-management-security skill may activate
  ├─ Matches: "JWT" in request
  ├─ Loads: Token validation, expiration, storage
  └─ Suggests: Strong algorithms, proper validation

→ secrets-management skill may activate
  ├─ Matches: "authentication" implies secrets
  ├─ Loads: Environment variables, key storage
  └─ Suggests: Load JWT secret from env, not hardcode

Claude writes code following skill guidance:
✅ Uses bcrypt for passwords (from authentication-security skill)
✅ Implements proper JWT validation (from session-management skill)
✅ Loads secrets from environment (from secrets-management skill)

// ============================================================
// STEP 3: Claude Attempts Commit (Hooks Execute - Guaranteed)
// ============================================================
Claude: "git commit -m 'Add JWT authentication'"

PreToolUse hook ALWAYS executes (100% guaranteed):
→ Runs: python3 .claude/hooks/validate_security.py
→ Scans code for:
  ├─ Weak crypto (MD5, SHA1, DES)
  ├─ Hardcoded secrets (API_KEY = "...", PASSWORD = "...")
  ├─ SQL injection patterns (string concatenation in queries)
  ├─ Command injection (subprocess with shell=True)
  ├─ Path traversal (open(user_input) without validation)
  └─ [... all security rules ...]

// ============================================================
// STEP 4a: If Hook Finds Violations (Enforcement)
// ============================================================
Hook detects: hashlib.md5(password.encode())  # WEAK CRYPTO!

Hook BLOCKS commit and returns to Claude:
❌ SECURITY VIOLATION DETECTED
   - File: src/auth/login.py:42
   - Issue: MD5 used for password hashing
   - Rule: CRYPTO-001 (Weak cryptographic algorithm)
   - Fix: Use bcrypt.hashpw() or argon2.hash()

Claude sees violation feedback:
→ Optionally invokes comprehensive-security-agent for deep analysis
→ Agent provides detailed remediation with code examples
→ Claude fixes the issue
→ Tries commit again (hook re-validates)

// ============================================================
// STEP 4b: If Hook Finds No Violations (Success)
// ============================================================
Hook validation passes:
✅ All security rules satisfied
✅ No weak crypto detected
✅ No hardcoded secrets found
✅ Input validation present

Hook allows commit:
→ Code committed successfully
→ Security validation complete

Why This Three-Layer Approach Works

Layer 1: Skills (Proactive)

• Benefit: Reduces violations at code creation time
• Limitation: Not guaranteed to activate
• Value: When they work, violations never happen
• Coverage: Probabilistic with well-written descriptions

Layer 2: Hooks (Enforcement)

• Benefit: Catches EVERYTHING skills miss
• Limitation: Reactive (after code written, before commit)
• Value: 100% guaranteed execution
• Coverage: 100% - no code escapes validation

Layer 3: Agents (Deep Analysis)

• Benefit: Comprehensive multi-domain analysis
• Limitation: Higher token cost, longer execution
• Value: Detailed remediation when needed
• Coverage: Triggered only when violations detected

Hook Implementation Example

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/security_validator.py --tool Write"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/security_validator.py --tool Bash"
          }
        ]
      }
    ]
  }
}

# .claude/hooks/security_validator.py
"""
Security validation hook - guaranteed execution before commits/writes
Validates against all 191 security rules from compiled rule cards
"""
import sys
import json
from pathlib import Path

def validate_security(tool, input_data, mode):
    """Run security validation against rule cards"""

    # Load all security rules
    rules_dir = Path(".claude/agents/json")
    violations = []

    for rule_file in rules_dir.glob("*.json"):
        rules = json.loads(rule_file.read_text())

        # Check each rule's detection patterns
        for rule in rules.get("rules", []):
            if check_violation(input_data, rule):
                violations.append({
                    "file": extract_file_from_input(input_data),
                    "rule_id": rule["id"],
                    "severity": rule["severity"],
                    "description": rule["description"],
                    "remediation": rule["remediation"]
                })

    if violations:
        # BLOCK operation and return violations to Claude
        print(json.dumps({
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": f"SECURITY VIOLATIONS DETECTED - {len(violations)} issues found",
                "updatedInput": None
            },
            "violations": violations
        }))
        sys.exit(1)

    # Allow operation
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
            "permissionDecisionReason": "No security violations detected",
            "updatedInput": None
        }
    }))
    sys.exit(0)

if __name__ == "__main__":
    # Hook receives environment variables from Claude Code
    tool = sys.argv[1].replace("--tool", "").strip()
    input_data = os.getenv("CLAUDE_TOOL_INPUT")

    validate_security(tool, input_data, None)

Key Decision: When to Use Each Layer

Critical Insight

Skills alone are NOT sufficient for security-critical codebases:

❌ WRONG: Rely only on skills
   → Skills may not activate
   → Violations can slip through
   → No enforcement mechanism

✅ RIGHT: Skills + Hooks + Agents
   → Skills reduce violations proactively
   → Hooks enforce rules deterministically
   → Agents provide deep analysis when needed
   → Defense-in-depth security

For this security-focused repository: ALL THREE LAYERS ARE REQUIRED.

Migration Strategy: Validation-First Approach

Current State (Verified Reality)

What Actually Exists:

• ✅ 21 JSON rule files in .claude/agents/json/ (not "15+" - actual count: 21)
• ✅ 1 skill implemented: authentication-security/SKILL.md
• ✅ Symlink confirmed: authentication-security/rules.json → ../agents/json/authentication-specialist.json
• ✅ Agent markdown files in .claude/agents/ for sub-agent invocation

What Does NOT Exist:

• ❌ No .claude/settings.json (hooks not implemented)
• ❌ No .claude/hooks/ directory or validation scripts
• ❌ No evidence that authentication-security skill auto-activates
• ❌ No metrics on skill activation rates, token usage, or effectiveness
• ❌ No validation of semantic matching behavior

Critical Gap: We have infrastructure but ZERO validation that it works as designed.

Migration Principle: Verify Before Scale

DO NOT create 14 more skills before validating the first one works.

DO NOT implement hooks before proving skills provide value.

DO NOT set numeric targets (">85% activation") without baseline measurements.

Phase 0: Validate Core Assumptions (REQUIRED - 2-3 days)

This phase MUST succeed before proceeding to Phase 1.

Test 1: Skill Auto-Activation Validation

Goal: Prove authentication-security skill actually auto-activates based on semantic matching

Method:

1. Create 20 test prompts:
   • 10 authentication-related: "Review login code", "Check password hashing", "Analyze JWT authentication", etc.
   • 10 unrelated: "Parse JSON file", "Optimize database query", "Fix CSS layout", etc.
2. For each prompt, observe Claude's behavior
3. Document which prompts trigger skill activation
4. Measure actual token usage during activation

Success Criteria:

• ✅ Skill loads on ≥8/10 authentication-related prompts (80% true positive)
• ✅ Skill does NOT load on ≥9/10 unrelated prompts (<10% false positive)
• ✅ Can articulate WHY certain prompts matched (semantic understanding)
• ✅ Have actual token measurements (not guesses)

If FAILS:

• Refine skill description
• Test alternative descriptions
• If still fails: skills may not work as documented → STOP and reassess

Test 2: Progressive Disclosure Validation

Goal: Verify skills load incrementally, not all-at-once

Method:

1. Monitor what gets loaded when skill activates
2. Check if rules.json loads immediately or on-demand
3. Test with simple prompt vs complex violation
4. Measure token usage at each stage

Success Criteria:

• ✅ Evidence of staged loading (description → SKILL.md → rules.json)
• ✅ Actual token measurements for each stage
• ✅ Rules.json only loads when needed (not always)

If FAILS:

• Skills may load too much context upfront
• May need restructuring

Test 3: Skill Value Validation

Goal: Prove skills actually provide security guidance

Method:

1. Give Claude code with auth vulnerabilities (MD5 password hashing, hardcoded secrets)
2. Test WITH skill activated
3. Test WITHOUT skill activated (control)
4. Compare quality of security recommendations

Success Criteria:

• ✅ WITH skill: Claude catches vulnerabilities
• ✅ WITHOUT skill: Claude misses or provides weaker guidance
• ✅ Measurable difference in security advice quality

If FAILS:

• Skills may not add value
• May need better content in SKILL.md
• Consider whether agent invocation is sufficient

STOP GATE: Phase 0 must demonstrate measurable value before proceeding.

Phase 1: Incremental Skill Creation (CONDITIONAL - timing TBD)

Prerequisites: Phase 0 tests pass with clear evidence skills work

Process: Create ONE skill at a time, validate, then proceed

Per-Skill Validation Process:

1. Create {domain}-security/SKILL.md
2. Test auto-activation (minimum 10 prompts)
3. Measure true positive rate, false positive rate
4. Refine description if activation rate <70%
5. ONLY create next skill after validation succeeds

Skills Priority Order (by expected frequency):

1. ✅ authentication-security (exists - validate in Phase 0)
2. ⬜ input-validation-security (high frequency - SQL injection, XSS)
3. ⬜ secrets-management-security (high frequency - API keys, credentials)
4. ⬜ session-management-security (moderate frequency)
5. ⬜ cryptography-security (moderate frequency)
6. ⬜ [Continue ONLY if previous skills validate successfully]

Stop Conditions:

• Any skill fails validation (<70% true positive OR >20% false positive)
• Token usage per skill exceeds reasonable limits (define limit based on Phase 0 data)
• Diminishing returns (skill provides no new value over existing skills)

DO NOT create all 14 skills blindly. Create, validate, learn, adjust.

Phase 2: Minimal Hook Implementation (CONDITIONAL - 1 week)

Prerequisites:

• Phase 0 proves skills provide value
• At least 3 skills validated and working
• Clear understanding of token costs

Step 1: Minimal Viable Hook (1-2 days)

Create simplest possible hook to validate mechanism works:

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "python3 .claude/hooks/minimal_validator.py"
      }]
    }]
  }
}

# .claude/hooks/minimal_validator.py
# Test: detect hardcoded "password123" only
import json, sys, os

input_data = os.getenv("CLAUDE_TOOL_INPUT", "")
if "password123" in input_data:
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Hardcoded password detected (test)",
            "updatedInput": None
        }
    }))
    sys.exit(1)

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
        "permissionDecisionReason": "No test violation",
        "updatedInput": None
    }
}))
sys.exit(0)

Validation:

• ✅ Hook actually executes on Write tool use
• ✅ permissionDecision: "deny" actually blocks the write
• ✅ Claude receives and understands the feedback
• ✅ Can unblock by removing violation

If FAILS: Fix hook mechanism before adding complexity

Step 2: Single Real Rule (1-2 days)

Add ONE security rule (e.g., detect hashlib.md5 in Python code):

• Test detection works on real code
• Measure false positive rate
• Test Claude's response to violation feedback
• Verify violation → fix → retry flow works

Step 3: Expand Incrementally (ONLY if Step 1+2 succeed)

• Add rules one domain at a time
• Validate each addition doesn't spike false positives
• Monitor performance impact
• Roll back if accuracy degrades

DO NOT load all 191 rules at once. Incremental, validated expansion only.

Phase 3: Hook-Agent Integration (CONDITIONAL - timing TBD)

Prerequisites:

• Phase 0: Skills validated
• Phase 2: Hooks validated with acceptable false positive rate
• Clear metrics on when agent invocation adds value

Goal: Hooks trigger agent analysis on violations

Implementation:

• Hook detects violation
• Hook calls Agent SDK to invoke specialist agent
• Agent provides detailed remediation
• Feedback loops back to Claude

Validation:

• Measure remediation quality WITH agent vs WITHOUT
• Measure token cost of agent invocation
• Measure time cost
• Ensure agent adds value beyond hook message

If agent doesn't add measurable value over hook feedback alone: Skip this phase

Validation Metrics (Measured, Not Targets)

DO NOT set targets before baseline measurement.

Metrics to MEASURE (not predict):

• Skill activation rate (true positive, false positive, false negative)
• Token usage per skill activation (actual numbers)
• Hook detection accuracy (true positive, false positive rates)
• Agent remediation value (measurable improvement vs hook-only)
• End-to-end time cost

After measurement, THEN decide if metrics are acceptable.

If metrics show approach isn't working: pivot or stop, don't force it.

Recommendation: Embrace the Three-Layer Architecture

Implement skills, hooks, AND agents for defense-in-depth:

Benefits:

• ✅ Layer 1 (Skills): Proactive guidance reduces violations before they happen
• ✅ Layer 2 (Hooks): Guaranteed enforcement catches everything skills miss
• ✅ Layer 3 (Agents): Deep analysis provides comprehensive remediation
• ✅ Backward compatible (existing agent workflows unchanged)
• ✅ Token efficient (skills auto-activate, agents only when needed)
• ✅ Security-first (100% coverage through hooks)

Implementation:

1. Skills in .claude/skills/ - Auto-discovery and proactive guidance
2. Hooks in .claude/settings.json - Mandatory security validation
3. Agents in .claude/agents/ - Explicit parallel execution and deep analysis
4. Shared rules via symlinks - Single source of truth (no duplication)

Architecture:

.claude/
├── skills/                          # Layer 1: Proactive Guidance
│   ├── authentication-security/
│   ├── session-management-security/
│   └── [... 15 security domains]
│
├── settings.json                    # Layer 2: Hook Configuration
├── hooks/
│   ├── security_validator.py       # Validates all commits/writes
│   └── utils/                       # Rule loading & pattern matching
│
└── agents/                          # Layer 3: Deep Analysis
    ├── authentication-specialist.md
    ├── [... 15 specialist agents]
    └── json/                        # Shared security rules
        └── *.json                   # 191 rules across 20 domains

Result - Complete Security Coverage:

Interactive Development:
- User: "Add JWT authentication"
  → Skills auto-activate (guidance)
  → Claude writes secure code
  → Hooks validate before commit (enforcement)
  → If violations: Agents provide remediation (analysis)

Pre-Commit Validation:
- Developer commits code
  → Hooks ALWAYS validate (100% coverage)
  → Block if violations detected
  → Trigger agents for detailed analysis
  → Provide actionable remediation

CI/CD Pipeline:
- Pipeline runs security scan
  → Hooks validate all changes
  → Agents run in parallel for comprehensive analysis
  → Generate security report
  → Block merge if violations found

Conclusion: Skills, hooks, and agents form a comprehensive three-layer security architecture. Skills provide proactive guidance through automatic context injection. Hooks provide guaranteed enforcement that catches everything skills miss. Agents provide deep parallel analysis when violations occur. Together, they deliver defense-in-depth security with 100% coverage for security-critical codebases.

Detailed Comparison

Context Loading

Agent (Reference-Based):

┌──────────────────────────────────────┐
│ Step 1: Load Agent Instructions     │ moderate cost
│ - Agent frontmatter                  │
│ - Analysis approach                  │
│ - Tool descriptions                  │
└──────────────────────────────────────┘
         ↓ (when analysis needed)
┌──────────────────────────────────────┐
│ Step 2: Load JSON Rule File         │ larger cost
│ - Read json/{agent-name}.json        │
│ - All rules, detection patterns      │
│ - References (ASVS, CWE, OWASP)      │
└──────────────────────────────────────┘

Skill (Progressive):

┌─────────────────────┐
│ Step 1: Overview    │ small cost (discovery)
│ - Name + description│
└─────────────────────┘
         ↓ (semantic match)
┌─────────────────────┐
│ Step 2: Load SKILL  │ moderate cost
│ - Full instructions │
│ - Capabilities      │
│ - Usage patterns    │
└─────────────────────┘
         ↓ (if needed)
┌─────────────────────┐
│ Step 3: Full Rules  │ larger cost
│ - Load rules.json   │
│ - All detection     │
└─────────────────────┘

Final Summary: Skills and agents are complementary tools in a hybrid architecture. Skills provide automatic context injection through semantic matching and progressive disclosure. Agents provide explicit parallel execution for programmatic workflows. Both share the same security rule knowledge base through symlinks, ensuring consistency without duplication.

Use skills for interactive workflows where Claude auto-detects what knowledge to apply. Use agents for programmatic workflows where you explicitly control which specialists run in parallel. Together, they provide the complete security analysis capability.