gh-basher83-lunar-claude-plugins-devops-python-tools/commands/new-sdk-app.md

description, argument-hint

description	argument-hint
Create and setup a new Claude Agent SDK application (Python)	project-name

You are tasked with helping the user create a new Claude Agent SDK application using Python. Follow these steps carefully:

Reference Documentation

Before starting, use the claude-agent-sdk skill to ensure you follow SDK best practices:

# Load the skill to access patterns and examples
/skill claude-agent-sdk

The skill provides:

• SDK templates (assets/sdk-template.py)
• Official examples (examples/)
• Best practices and patterns (references/)
• Validation checklist (assets/sdk-validation-checklist.md)

Also reference the official documentation:

• Python SDK reference: https://docs.claude.com/en/api/agent-sdk/python

IMPORTANT: Always check for and use the latest SDK version (targeting >= 0.1.6).

Gather Requirements

IMPORTANT: Ask these questions one at a time. Wait for the user's response before asking the next question. This makes it easier for the user to respond.

Ask the questions in this order (skip any that the user has already provided via arguments):

1. Project name (ask first): "What would you like to name your project?"

   • If $ARGUMENTS is provided, use that as the project name and skip this question
   • Wait for response before continuing

2. Agent type (ask second, but skip if #1 was sufficiently detailed): "What kind of agent are you building? Some examples:

   • Coding agent (SRE, security review, code review)
   • Orchestrator with subagents (multi-agent workflows)
   • Business agent (customer support, content creation)
   • Custom agent (describe your use case)"
   • Wait for response before continuing

3. Starting point (ask third): "Would you like:

   • A minimal query() example for simple tasks
   • A ClaudeSDKClient example for multi-turn conversations
   • An orchestrator with subagents
   • Start from the SDK template (assets/sdk-template.py)"
   • Wait for response before continuing

4. Project structure (ask fourth): "What project structure would you prefer:

   • Single-file uv script (self-contained with # /// script header)
   • Standard Python project with pyproject.toml"
   • Wait for response before continuing

After all questions are answered, proceed to create the setup plan.

Setup Plan

Based on the user's answers, create a plan that includes:

1. Project initialization:

   • Create project directory (if it doesn't exist)
   • For uv scripts: Create single Python file with # /// script header including claude-agent-sdk dependency
   • For standard projects:
     • Initialize with pyproject.toml
     • Add claude-agent-sdk to dependencies
     • Configure Python version requirements (>= 3.8)

2. Check for Latest Versions:

   • BEFORE installing, check PyPI for the latest version: https://pypi.org/project/claude-agent-sdk/
   • Inform the user which version you're using (targeting >= 0.1.6)

3. SDK Installation:

   • For uv scripts: Dependencies specified in script header, no separate installation needed
   • For standard projects:
     • Install with pip install claude-agent-sdk or add to pyproject.toml
     • After installation, verify with pip show claude-agent-sdk

4. Create starter files:

   Based on user's choice:

   • query() example: Simple one-shot task (no conversation memory)
   • ClaudeSDKClient example: Multi-turn conversation with context
   • Orchestrator: Main orchestrator with programmatically registered subagents
   • SDK template: Copy from assets/sdk-template.py and customize

   All files should include:

   • Proper imports (claude_agent_sdk, anyio)
   • SDK best practices (system_prompt, allowed_tools, permission_mode)
   • Error handling
   • Clear comments explaining each part

5. Authentication setup:

   • Explain that the SDK uses local Claude Code authentication
   • No .env files needed when running with Claude Code
   • If running standalone, API key can be set via environment variable

6. Optional: Create .claude directory structure:

   • Offer to create .claude/agents/ directory for subagent definitions
   • Provide example agent markdown files if building an orchestrator

Implementation

After gathering requirements and getting user confirmation on the plan:

1. Check for latest SDK version on PyPI
2. Execute the setup steps
3. Create all necessary files based on project structure choice:
   • Uv script: Single file with proper script header
   • Standard project: pyproject.toml + source files
4. Install dependencies if standard project (uv scripts handle deps automatically)
5. Verify installed versions and inform the user
6. Create a working example based on their starting point:
   • Use patterns from the claude-agent-sdk skill
   • Reference examples from examples/ directory
   • Follow SDK best practices
7. Add helpful comments explaining SDK concepts:
   • What ClaudeAgentOptions does
   • Why system_prompt="claude_code" for orchestrators
   • Tool restrictions and permission modes
   • Async runtime choice (anyio vs asyncio)
8. VERIFY THE CODE WORKS BEFORE FINISHING:
   • Verify imports are correct
   • Check for syntax errors
   • Validate SDK patterns match documentation
   • Ensure agent names match if using orchestrator
   • DO NOT consider the setup complete until the code verifies successfully

Verification

After all files are created and dependencies are installed, launch the agent-sdk-verifier-py agent to validate that the Agent SDK application is properly configured and ready for use:

1. Use the Task tool to launch the agent-sdk-verifier-py subagent
2. The agent will check:
   • SDK installation and configuration
   • Proper imports and SDK patterns
   • query() vs ClaudeSDKClient usage
   • Orchestrator requirements (system_prompt, Task tool, agent registration)
   • Permission and security settings
   • Best practices adherence
3. Review the verification report and address any issues before completing setup

Getting Started Guide

Once setup is complete and verified, provide the user with:

1. Next steps:

   • For uv scripts: Run with uv run <script-name>.py (automatically handles dependencies)
   • For standard projects:
     • Activate virtual environment if needed
     • Run with python main.py or python src/main.py
   • Authentication uses local Claude Code session (no API key setup needed)

2. Useful resources:

   • Python SDK reference: https://docs.claude.com/en/api/agent-sdk/python
   • claude-agent-sdk skill: /skill claude-agent-sdk for patterns and examples
   • Key concepts to explore:
     • System prompts (preset vs custom)
     • Permissions (permission_mode and callbacks)
     • Tools (allowed_tools restrictions)
     • MCP servers (custom tools)
     • Subagents (programmatic registration)

3. Common next steps:

   • Customize the system prompt for your use case
   • Add custom tools via SDK MCP servers (see examples/mcp_calculator.py)
   • Configure permission callbacks for fine-grained control
   • Create and register subagents programmatically
   • Review examples in the skill: examples/hooks.py, examples/streaming_mode.py
   • Validate changes with assets/sdk-validation-checklist.md

Important Notes

• ALWAYS USE LATEST SDK VERSION: Check PyPI for the latest version (targeting >= 0.1.6)
• VERIFY CODE WORKS BEFORE FINISHING:
  • Verify imports are correct
  • Check syntax
  • Validate SDK patterns (query() vs ClaudeSDKClient, system_prompt, tools)
  • Ensure agent names match if using orchestrator
  • Launch agent-sdk-verifier-py for comprehensive validation
  • Do NOT consider the task complete until verification passes
• USE THE CLAUDE-AGENT-SDK SKILL: Reference patterns and examples from the skill
• FOLLOW SDK BEST PRACTICES:
  • Use system_prompt="claude_code" for orchestrators
  • Register agents programmatically via agents={}
  • Include "Task" in orchestrator's allowed_tools
  • Choose appropriate runtime (anyio.run or asyncio.run)
  • Restrict tools to minimum needed per agent
• Always check if directories/files already exist before creating them
• Ensure all code examples are functional and include proper error handling
• Use patterns compatible with the latest SDK version
• Make the experience interactive and educational
• ASK QUESTIONS ONE AT A TIME - Do not ask multiple questions in a single response

Begin by asking the FIRST requirement question only. Wait for the user's answer before proceeding to the next question.