Agent SDK Dev — SDK Scaffolding & Verification

Development Kit for Claude Agent SDK Applications

Interactive scaffolding and verification toolkit for creating Claude Agent SDK applications in Python and TypeScript. Guides developers through project setup with /new-sdk-app, scaffolds the project structure, and runs language-specific verifiers to ensure correctness.

Agents

Command

Files

Language

🤖 SDK Dev Kit🐍 Python SDK📘 TypeScript SDK✅ Verification

📚 What is this & why does it exist?

Agent SDK Dev removes the boilerplate friction from starting new Claude Agent SDK projects. The /new-sdk-app command asks a series of guided questions (language, project name, features), then scaffolds a complete project with proper structure, dependencies, and configuration. After scaffolding, a language-specific verifier agent (Python or TypeScript) validates that the generated code compiles, imports resolve, and the basic agent loop works correctly.

💡 Real-world analogy

Think of a car dealership's “build your vehicle” configurator. You answer questions about engine type, color, and features. The system generates a complete vehicle specification, sends it to the factory floor (scaffolding), and then runs quality checks before delivery (verification). Agent SDK Dev is that configurator for AI agent projects — you pick your language, name your app, choose features, and get a verified, ready-to-run project.

Architecture

flowchart TB
    subgraph Setup["Interactive Setup"]
        CMD["/new-sdk-app"] --> Q1["Language? Python / TypeScript"]
        Q1 --> Q2["Project name?"]
        Q2 --> Q3["Features? Tools, MCP, Hooks"]
        Q3 --> Q4["Output directory?"]
    end
    subgraph Scaffold["Project Scaffolding"]
        Q4 --> SC["Generate project structure"]
        SC --> DEP["Write dependency files"]
        DEP --> CFG["Write configuration"]
        CFG --> SRC["Generate source code"]
    end
    subgraph Verify["Verification"]
        SRC -->|Python| VPY["agent-sdk-verifier-py"]
        SRC -->|TypeScript| VTS["agent-sdk-verifier-ts"]
        VPY --> RPT["Verification Report"]
        VTS --> RPT
    end
    RPT --> OUT["Ready-to-run Project"]

Key Components

Component	File	Role
`new-sdk-app`	`commands/new-sdk-app.md`	Interactive guided command — collects preferences and orchestrates scaffolding
`agent-sdk-verifier-py`	`agents/agent-sdk-verifier-py.md`	Python verifier — checks imports, venv setup, type hints, agent loop execution
`agent-sdk-verifier-ts`	`agents/agent-sdk-verifier-ts.md`	TypeScript verifier — checks compilation, package resolution, type safety, agent loop
`plugin.json`	`.claude-plugin/plugin.json`	Plugin manifest registering the command and both verifier agents
`README.md`	`README.md`	Usage documentation with examples for both Python and TypeScript flows

Verifier Agent Details

Verifier	Model	Checks Performed	Tools Used
`agent-sdk-verifier-py`	Sonnet	Import resolution, venv creation, pip install, type checking (mypy), agent loop dry run	Bash, Read, Grep
`agent-sdk-verifier-ts`	Sonnet	Package install (npm/pnpm), TypeScript compilation (tsc), import resolution, agent loop dry run	Bash, Read, Grep

Workflow Example

Basic Usage

# Create a new Python Agent SDK app
/new-sdk-app

# The command will interactively ask:
# 1. Language: Python or TypeScript?
# 2. Project name?
# 3. Features: Tools, MCP, Hooks?
# 4. Output directory?

Verification Checks

🐍 Python Verification Steps

Verify pyproject.toml has valid TOML syntax
Create virtual environment (python -m venv .venv)
Install dependencies (pip install -e .)
Check all imports resolve correctly
Run mypy type checking (if installed)
Execute agent loop dry run (no API calls)
Verify test file imports and structure

📘 TypeScript Verification Steps

Verify package.json has valid JSON
Verify tsconfig.json configuration
Install packages (npm install)
Run TypeScript compiler (tsc --noEmit)
Check all module imports resolve
Verify exported types are correct
Execute agent loop dry run (no API calls)

Supported SDK Features

Feature	Python	TypeScript	Description
Basic Agent Loop	✅	✅	Core message loop with Claude client
Custom Tools	✅	✅	Tool definitions with input schemas and handlers
MCP Integration	✅	✅	Model Context Protocol server configuration
Hook System	✅	✅	Pre/post tool use hooks for validation
Streaming	✅	✅	Streaming response support
Multi-turn	✅	✅	Conversation history management
Error Recovery	✅	✅	Retry logic and error handling patterns

Data Flow

sequenceDiagram
    participant Dev as Developer
    participant Cmd as /new-sdk-app
    participant FS as File System
    participant VPY as verifier-py
    participant VTS as verifier-ts

    Dev->>Cmd: /new-sdk-app
    Cmd->>Dev: What language? (Python / TypeScript)
    Dev->>Cmd: Python
    Cmd->>Dev: Project name?
    Dev->>Cmd: my-agent
    Cmd->>Dev: Features? (Tools, MCP, Hooks)
    Dev->>Cmd: Tools + MCP
    Cmd->>FS: Create project directory
    Cmd->>FS: Write pyproject.toml
    Cmd->>FS: Write src/agent.py
    Cmd->>FS: Write src/tools.py
    Cmd->>FS: Write src/mcp_config.py
    Cmd->>FS: Write README.md
    Note over Cmd: Scaffolding complete
    Cmd->>VPY: Verify Python project
    VPY->>FS: Check file structure
    VPY->>VPY: Create venv, pip install
    VPY->>VPY: Run mypy type check
    VPY->>VPY: Dry run agent loop
    VPY-->>Cmd: Verification report (pass/fail)
    Cmd-->>Dev: Project ready with report

Error Handling

The scaffolding and verification pipeline handles errors at each stage:

Stage	Error	Recovery
Scaffolding	Directory already exists	Prompt user: overwrite, rename, or cancel
Scaffolding	Invalid project name	Suggest sanitized name, re-prompt
Verification	Dependency install fails	Report missing packages, suggest manual fixes
Verification	Type check errors	List specific errors with file:line, suggest corrections
Verification	Agent loop fails	Report error trace, check API key configuration

Verification Report Format

## Verification Report: my-agent (Python)

| Check | Status | Details |
|-------|--------|---------|
| File structure | ✅ Pass | All expected files present |
| Dependencies | ✅ Pass | pip install completed (12 packages) |
| Import resolution | ✅ Pass | All imports resolve correctly |
| Type checking | ⚠️ Warn | 2 mypy warnings (non-blocking) |
| Agent loop | ✅ Pass | Dry run completed successfully |

**Result: READY** — Project is ready for development.

Interactions

Module	Interface	Data Exchanged
Claude Agent SDK (Python)	`anthropic` package	Scaffolded code imports and configures the Python Agent SDK
Claude Agent SDK (TypeScript)	`@anthropic-ai/sdk`	Scaffolded code imports and configures the TypeScript Agent SDK
File System	Write tool	Creates project directory, source files, configs, and dependencies
Package Managers	`pip` / `npm` / `pnpm`	Verifiers install dependencies to test resolution
Type Checkers	`mypy` / `tsc`	Verifiers run type checking as part of validation

Scaffolded Project Structure

🐍 Python Project

pyproject.toml — Dependencies and project metadata
src/agent.py — Main agent loop with Claude client
src/tools.py — Tool definitions and handlers
src/mcp_config.py — MCP server configuration
tests/test_agent.py — Basic agent tests
README.md — Getting started guide

📘 TypeScript Project

package.json — Dependencies and scripts
tsconfig.json — TypeScript configuration
src/agent.ts — Main agent loop with Claude client
src/tools.ts — Tool definitions and handlers
src/mcp-config.ts — MCP server configuration
tests/agent.test.ts — Basic agent tests
README.md — Getting started guide

Configuration Reference

Parameter	Default	Description
`language`	(prompted)	Target language: `python` or `typescript`
`project_name`	(prompted)	Name for the generated project directory
`features`	[]	Optional features to include: `tools`, `mcp`, `hooks`
`output_dir`	./	Parent directory for the scaffolded project
`verifier.model`	sonnet	Model used by verifier agents
`verifier.tools`	Bash,Read,Grep	Tools available to verifier agents
`python.min_version`	3.10	Minimum Python version in pyproject.toml
`typescript.target`	ES2022	TypeScript compilation target
`sdk.version`	latest	Claude Agent SDK version to pin in dependencies

Directory Map

Source tree for Agent SDK Dev

agent-sdk-dev/
├── .claude-plugin/plugin.json          ← Plugin manifest
├── README.md                           ← Usage documentation
├── commands/
│   └── new-sdk-app.md                  ← Interactive scaffolding command
└── agents/
    ├── agent-sdk-verifier-py.md        ← Python project verifier
    └── agent-sdk-verifier-ts.md        ← TypeScript project verifier