---
description: Review and validate a Claude Agent SDK application against best practices
argument-hint: [path-to-app]
---

# Review Claude Agent SDK Application

You are tasked with reviewing a Claude Agent SDK (Python) application to ensure
it follows SDK best practices and official documentation patterns. Follow these
steps carefully:

## Reference Documentation

Before starting, load the **claude-agent-sdk skill** to access patterns, examples, and the validation checklist:

```bash
# Load the skill for comprehensive SDK knowledge
/skill claude-agent-sdk
```

The skill provides:

- **Validation checklist**: `assets/sdk-validation-checklist.md` (comprehensive review guide)
- **SDK patterns**: `SKILL.md` and `references/` (official best practices)
- **Working examples**: `examples/` (reference implementations)
- **Template**: `assets/sdk-template.py` (ideal structure)

## Review Approach

You have TWO options for reviewing SDK applications:

### Option 1: Automated Validation (Recommended)

Launch the **agent-sdk-verifier-py** subagent for comprehensive automated review:

```bash
# The subagent will:
# - Read all application files
# - Check SDK patterns and configuration
# - Validate against official documentation
# - Provide detailed report with specific issues and recommendations
```

**Best for:**

- Quick validation
- New applications
- Pre-deployment checks
- Comprehensive coverage

### Option 2: Manual Guided Review

Follow the validation checklist step-by-step with guided assistance.

**Best for:**

- Learning SDK patterns
- Understanding specific issues
- Deep dive into SDK concepts
- Educational reviews

## Gather Information

Ask the user (if not provided via $ARGUMENTS):

1. **Application path**: "What is the path to your SDK application?"
   - If $ARGUMENTS is provided, use that as the application path
   - Wait for response before continuing

2. **Review type**: "Would you like:
   - Automated validation (launch agent-sdk-verifier)
   - Manual guided review (step-by-step checklist)
   - Both (automated first, then deep dive on issues)"
   - Wait for response before continuing

## Automated Validation Flow

If user chooses automated validation:

1. **Launch verifier agent**:
   - Use Task tool to launch `agent-sdk-verifier` subagent
   - Provide the application path to the agent
   - Wait for verification report

2. **Review the report**:
   - **Overall Status**: PASS | PASS WITH WARNINGS | FAIL
   - **Critical Issues**: Must be fixed before deployment
   - **Warnings**: Suboptimal patterns or improvements
   - **Passed Checks**: Correctly configured elements
   - **Recommendations**: Specific improvements with references

3. **Address issues**:
   - For each critical issue: explain the problem and provide fix
   - For warnings: explain why the recommendation matters
   - Reference specific skill documentation for context

4. **Re-validate if changes made**:
   - After fixes, offer to re-run validation
   - Ensure all critical issues are resolved

## Manual Guided Review Flow

If user chooses manual review, systematically work through the validation
checklist (`assets/sdk-validation-checklist.md`):

### Section 1: Imports & Dependencies

Read the application files and check:

- [ ] Async runtime import (anyio or asyncio)
- [ ] Claude SDK imports are accurate
- [ ] UV script headers (if single-file script)

**Ask user**: "Found any issues with imports? (Y/N)"

If yes, explain the issue and show correct pattern from skill examples.

### Section 2: Async Runtime

Check:

- [ ] Runtime execution (`anyio.run()` or `asyncio.run()`)
- [ ] Async/await patterns are correct
- [ ] Context managers for ClaudeSDKClient

**Ask user**: "Found any issues with async patterns? (Y/N)"

### Section 3: query() vs ClaudeSDKClient Choice

Check:

- [ ] Correct approach for use case
- [ ] Not using hooks/custom tools with query()

**Ask user**: "Is the query()/ClaudeSDKClient choice appropriate? (Y/N)"

If no, explain when to use each approach (reference SKILL.md lines 29-44).

### Section 4: Orchestrator Configuration (if applicable)

Check:

- [ ] System prompt is `"claude_code"` for orchestrators
- [ ] Task tool is included in allowed_tools
- [ ] Agents are registered programmatically

**Ask user**: "Found any orchestrator configuration issues? (Y/N)"

### Section 5: Agent Definitions (if applicable)

Check:

- [ ] Agent structure is correct (description, prompt, tools, model)
- [ ] Agent names match between definition and usage
- [ ] Tools are restricted to minimum needed

**Ask user**: "Found any agent definition issues? (Y/N)"

### Section 6: Permission Control

Check:

- [ ] Permission strategy is appropriate
- [ ] Permission mode is valid
- [ ] Permission callback (if used) is correct

**Ask user**: "Found any permission issues? (Y/N)"

### Section 7: Hooks (if used)

Check:

- [ ] Hooks ONLY used with ClaudeSDKClient
- [ ] Hook types are supported (not using SessionStart, etc.)
- [ ] Hook signature is correct
- [ ] Hook output structure is valid

**Ask user**: "Found any hook issues? (Y/N)"

### Section 8: ClaudeSDKClient Usage (if applicable)

Check:

- [ ] Context manager pattern is used
- [ ] Query → receive_response flow
- [ ] Interrupts (if used) are correct

**Ask user**: "Found any ClaudeSDKClient usage issues? (Y/N)"

### Section 9: Message Handling

Check:

- [ ] Message types are checked correctly
- [ ] TextBlock extraction is correct
- [ ] ResultMessage handling

**Ask user**: "Found any message handling issues? (Y/N)"

### Section 10: Error Handling

Check:

- [ ] API key validation (if running standalone)
- [ ] Safe dictionary access
- [ ] Async exception handling

**Ask user**: "Found any error handling issues? (Y/N)"

### Section 11: Settings & Configuration

Check:

- [ ] setting_sources is configured appropriately
- [ ] Model selection is appropriate
- [ ] Budget limits (if needed)

**Ask user**: "Found any configuration issues? (Y/N)"

### Section 12: Best Practices

Check:

- [ ] Follows DRY principle
- [ ] Clear comments and documentation
- [ ] Type hints are used
- [ ] No anti-patterns

**Ask user**: "Found any best practice violations? (Y/N)"

### Manual Review Summary

After completing all sections, provide:

```markdown
## Validation Summary

### ✅ Passed Checks:
- [List of passed checks]

### ❌ Issues Found:
- [List of issues with severity: CRITICAL | WARNING | INFO]

### 🔧 Fixes Required:
1. [Specific fix with file:line reference and code example]
2. [Specific fix with file:line reference and code example]

### 📊 Overall Assessment:
- **SDK Pattern Adherence**: [High/Medium/Low]
- **Production Ready**: [Yes/No/With Fixes]
- **Recommended Next Steps**: [Specific actions]
```

## Providing Fixes

For each issue identified:

1. **Explain the problem**:
   - Why it's an issue
   - What SDK pattern is being violated
   - Reference to skill documentation

2. **Show the correct pattern**:
   - Code example from skill examples or template
   - Explain why this pattern is preferred
   - Link to relevant skill reference

3. **Provide specific fix**:
   - Exact code change needed
   - File and line reference
   - Before/after comparison if helpful

## Follow-up Actions

After review:

1. **Offer to implement fixes**:
   - "Would you like me to implement these fixes?"
   - If yes, make changes and re-validate

2. **Suggest re-validation**:
   - "Would you like to run automated validation to confirm fixes?"
   - Launch agent-sdk-verifier-py if requested

3. **Recommend next steps**:
   - Additional features to consider
   - Testing recommendations
   - Deployment considerations

## Important Notes

- **USE THE VALIDATION CHECKLIST**: `assets/sdk-validation-checklist.md` is your comprehensive guide
- **REFERENCE SKILL DOCUMENTATION**: Always link to specific skill files for context
- **SHOW WORKING EXAMPLES**: Use examples from `examples/` directory
- **BE SPECIFIC**: Provide file:line references and exact code changes
- **EXPLAIN WHY**: Don't just identify issues, explain the SDK reasoning
- **PRIORITIZE ISSUES**: CRITICAL (breaks functionality) > WARNING (suboptimal) > INFO (nice to have)
- **VERIFY FIXES**: Re-validate after making changes
- **USE AGENT-SDK-VERIFIER-PY**: Leverage automated validation for comprehensive coverage

## Key SDK Patterns to Verify

Always check these common issues:

1. **Orchestrator missing system_prompt**: Must use `"claude_code"`
2. **Orchestrator missing Task tool**: Cannot delegate without it
3. **Agent name mismatches**: Definition name must match usage
4. **Hooks with query()**: Not supported, use ClaudeSDKClient
5. **Custom tools with query()**: Not supported, use ClaudeSDKClient
6. **Excessive tool permissions**: Restrict to minimum needed
7. **Missing agent registration**: Use `agents={}` parameter
8. **Wrong async runtime call**: Use `anyio.run()` or `asyncio.run()`
9. **Missing context manager**: ClaudeSDKClient requires `async with`
10. **Unsafe dictionary access**: Use `.get()` for optional fields

Begin by asking about the application path (if not provided) and review type preference.