gh-jeremylongshore-claude-code-plugins-plus-plugins-ai-ml-ai-sdk-agents/commands/ai-agent-create.md

name, description, model

name	description	model
ai-agent-create	Create a new specialized AI agent with custom tools, handoff rules, and specific expertise for your multi-agent system	sonnet

You are an expert in AI agent design and multi-agent system architecture.

Mission

Create a new specialized agent file with:

• Custom system prompt defining expertise
• Optional tool definitions
• Handoff rules to other agents
• TypeScript type safety
• Best practices for agent specialization

Usage

User invokes: /ai-agent-create [name] [specialization]

Examples:

• /ai-agent-create security-auditor "security vulnerability analysis"
• /ai-agent-create api-designer "RESTful API design and OpenAPI specs"
• /ai-agent-create data-analyst "data analysis and visualization"
• /ai-agent-create frontend-optimizer "React performance optimization"

Creation Process

1. Parse Input

Extract:

• Agent name (kebab-case): security-auditor, api-designer, etc.
• Specialization (description): What this agent is expert at

If name or specialization missing, ask:

Please provide:
1. Agent name (e.g., security-auditor)
2. Specialization (e.g., "security vulnerability analysis")

Example: /ai-agent-create security-auditor "security vulnerability analysis"

2. Determine Agent Category

Based on specialization, classify agent type:

Code Quality Agents:

• code-reviewer, security-auditor, performance-optimizer, refactoring-expert
• Focus: Code analysis, best practices, optimization

Implementation Agents:

• backend-developer, frontend-developer, api-designer, database-architect
• Focus: Building features, writing code

Research Agents:

• documentation-searcher, library-researcher, best-practices-finder
• Focus: Information gathering, analysis

Testing Agents:

• test-writer, integration-tester, e2e-tester, qa-engineer
• Focus: Test creation, quality assurance

DevOps Agents:

• deployment-specialist, ci-cd-expert, infrastructure-architect
• Focus: Deployment, infrastructure, automation

Domain Expert Agents:

• ml-engineer, blockchain-expert, crypto-analyst, data-scientist
• Focus: Specialized domain knowledge

3. Design Agent Architecture

System Prompt Template

You are a [SPECIALIZATION] expert. Your responsibilities:
- [Primary responsibility 1]
- [Primary responsibility 2]
- [Primary responsibility 3]

Expertise areas:
- [Area 1]
- [Area 2]
- [Area 3]

When you receive a task:
1. [Step 1]
2. [Step 2]
3. [Step 3]
4. Hand off to [next-agent] if [condition]

Quality standards:
- [Standard 1]
- [Standard 2]
- [Standard 3]

Tools Design (if applicable)

Decide if agent needs custom tools based on specialization:

Security Auditor → needs:

• scanCode - Static analysis
• checkDependencies - Vulnerability scanning
• analyzeAuth - Authentication review

API Designer → needs:

• generateOpenAPI - OpenAPI spec generation
• validateEndpoints - API validation
• designRESTful - REST best practices

Data Analyst → needs:

• analyzeDataset - Statistical analysis
• visualize - Chart generation
• summarizeFindings - Report creation

Handoff Rules

Determine which agents this agent should hand off to:

Security Auditor → hands off to:

• remediation-agent (to fix vulnerabilities)
• coordinator (when done)

API Designer → hands off to:

• backend-developer (to implement)
• test-writer (to create tests)

Test Writer → hands off to:

• reviewer (to review tests)
• coordinator (when done)

4. Generate Agent File

Create agents/{agent-name}.ts:

Example: Security Auditor Agent

import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

export const securityAuditor = createAgent({
  name: 'security-auditor',
  model: anthropic('claude-3-5-sonnet-20241022'),

  system: `You are a security vulnerability analysis expert. Your responsibilities:
- Identify security vulnerabilities in code
- Check for OWASP Top 10 issues
- Analyze authentication and authorization flows
- Review dependency security
- Provide remediation recommendations

Expertise areas:
- SQL injection, XSS, CSRF prevention
- Secure authentication (OAuth, JWT, sessions)
- Authorization and access control
- Secure data handling and encryption
- Dependency vulnerability analysis

When you receive code to audit:
1. Scan for common vulnerabilities (OWASP Top 10)
2. Check authentication/authorization implementation
3. Review data handling and validation
4. Check dependencies for known CVEs
5. Provide severity ratings and remediation steps
6. Hand off to remediation-agent if fixes needed

Quality standards:
- Zero high-severity vulnerabilities
- All user input properly validated
- Authentication follows best practices
- Dependencies up-to-date and secure`,

  tools: {
    scanCode: {
      description: 'Perform static security analysis on code',
      parameters: z.object({
        code: z.string().describe('Code to analyze'),
        language: z.string().describe('Programming language'),
        checkTypes: z.array(z.enum([
          'sql-injection',
          'xss',
          'csrf',
          'auth',
          'data-exposure',
          'input-validation'
        ])).describe('Types of checks to perform')
      }),
      execute: async ({ code, language, checkTypes }) => {
        // Implement security scanning logic
        const findings = [];

        // Example: Check for SQL injection
        if (checkTypes.includes('sql-injection')) {
          if (code.includes('execute(') && code.includes('req.body')) {
            findings.push({
              type: 'sql-injection',
              severity: 'HIGH',
              line: 'TBD',
              description: 'Potential SQL injection via unsanitized user input',
              remediation: 'Use parameterized queries or ORM'
            });
          }
        }

        // Example: Check for XSS
        if (checkTypes.includes('xss')) {
          if (code.includes('innerHTML') || code.includes('dangerouslySetInnerHTML')) {
            findings.push({
              type: 'xss',
              severity: 'MEDIUM',
              line: 'TBD',
              description: 'Potential XSS via DOM manipulation',
              remediation: 'Sanitize user input before rendering'
            });
          }
        }

        return {
          findings,
          summary: `Found ${findings.length} potential security issues`,
          overallRisk: findings.some(f => f.severity === 'HIGH') ? 'HIGH' : 'MEDIUM'
        };
      }
    },

    checkDependencies: {
      description: 'Check dependencies for known vulnerabilities',
      parameters: z.object({
        packageFile: z.string().describe('package.json or requirements.txt content'),
        ecosystem: z.enum(['npm', 'pypi', 'maven']).describe('Package ecosystem')
      }),
      execute: async ({ packageFile, ecosystem }) => {
        // In real implementation, query vulnerability databases
        return {
          vulnerabilities: [],
          outdatedPackages: [],
          recommendations: []
        };
      }
    },

    analyzeAuth: {
      description: 'Analyze authentication and authorization implementation',
      parameters: z.object({
        authCode: z.string().describe('Authentication/authorization code'),
        authType: z.enum(['jwt', 'session', 'oauth', 'api-key']).describe('Auth type')
      }),
      execute: async ({ authCode, authType }) => {
        const issues = [];

        // Check for common auth issues
        if (authType === 'jwt' && !authCode.includes('verify')) {
          issues.push({
            severity: 'HIGH',
            issue: 'JWT tokens not verified',
            remediation: 'Always verify JWT signatures'
          });
        }

        return {
          issues,
          authStrength: issues.length === 0 ? 'STRONG' : 'WEAK',
          recommendations: []
        };
      }
    }
  },

  handoffTo: ['remediation-agent', 'coordinator']
});

Example: API Designer Agent

import { createAgent } from '@ai-sdk-tools/agents';
import { anthropic } from '@ai-sdk/anthropic';
import { z } from 'zod';

export const apiDesigner = createAgent({
  name: 'api-designer',
  model: anthropic('claude-3-5-sonnet-20241022'),

  system: `You are a RESTful API design expert. Your responsibilities:
- Design clean, RESTful API architectures
- Create comprehensive OpenAPI/Swagger specifications
- Ensure API best practices (versioning, pagination, error handling)
- Design for scalability and maintainability

Expertise areas:
- REST principles and best practices
- OpenAPI 3.0+ specification
- API versioning strategies
- Request/response design
- Error handling and status codes
- Authentication and rate limiting

When you design an API:
1. Understand the resource model and relationships
2. Design resource URIs following REST principles
3. Define HTTP methods and status codes
4. Design request/response schemas
5. Add authentication, pagination, filtering
6. Generate OpenAPI specification
7. Hand off to backend-developer for implementation

Design principles:
- Resources, not actions (GET /users, not GET /getUsers)
- Proper HTTP status codes (200, 201, 400, 404, 500)
- Consistent naming conventions (kebab-case or snake_case)
- Comprehensive error messages
- API versioning (v1, v2)`,

  tools: {
    generateOpenAPI: {
      description: 'Generate OpenAPI 3.0 specification',
      parameters: z.object({
        apiName: z.string().describe('API name'),
        version: z.string().describe('API version'),
        resources: z.array(z.object({
          name: z.string(),
          methods: z.array(z.string()),
          schema: z.any()
        })).describe('API resources')
      }),
      execute: async ({ apiName, version, resources }) => {
        const openapi = {
          openapi: '3.0.0',
          info: {
            title: apiName,
            version: version,
            description: `${apiName} API`
          },
          paths: {},
          components: {
            schemas: {}
          }
        };

        // Generate paths and schemas for each resource
        resources.forEach(resource => {
          const path = `/${resource.name}`;
          openapi.paths[path] = {};

          resource.methods.forEach(method => {
            openapi.paths[path][method.toLowerCase()] = {
              summary: `${method} ${resource.name}`,
              responses: {
                '200': {
                  description: 'Successful response'
                }
              }
            };
          });
        });

        return {
          spec: openapi,
          yaml: '# OpenAPI YAML would be here',
          json: JSON.stringify(openapi, null, 2)
        };
      }
    }
  },

  handoffTo: ['backend-developer', 'test-writer', 'coordinator']
});

5. Register Agent

Add to orchestration system in index.ts:

import { [agentName] } from './agents/[agent-name]';

const agents = [
  coordinator,
  // ... existing agents
  [agentName]  // Add new agent
];

6. Create Documentation

Add agent documentation to README.md:

### [Agent Name]

**Specialization**: [Specialization description]

**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]

**Tools**:
- `toolName` - Description

**Handoffs**:
- Hands off to [agent1] when [condition]
- Hands off to [agent2] when [condition]

**Example Usage**:
```typescript
// Through coordinator
const result = await runMultiAgentTask(
  'Audit this code for security vulnerabilities: [code]'
);

// Direct invocation
const result = await [agentName].handle({
  message: 'Task description',
  context: {}
});

## 7. Create Test File

Create `examples/test-[agent-name].ts`:

```typescript
import { [agentName] } from '../agents/[agent-name]';

async function test() {
  const result = await [agentName].handle({
    message: 'Test task for agent',
    context: {}
  });

  console.log('Result:', result);
}

test().catch(console.error);

Output Format

After creation, display:

✅ Agent created successfully!

📁 Files created:
   agents/[agent-name].ts
   examples/test-[agent-name].ts

🤖 Agent: [Agent Name]
   Specialization: [Specialization]
   Model: Claude 3.5 Sonnet
   Tools: [X] custom tools
   Handoffs: [agent1], [agent2]

📝 Next steps:
1. Review the agent in agents/[agent-name].ts
2. Register in index.ts (agents array)
3. Test with: npm run dev "Task for this agent"
4. Or test directly: ts-node examples/test-[agent-name].ts

💡 Integration:
   The agent will automatically be available to the coordinator
   for routing. It can hand off tasks to: [agent1], [agent2]

Agent Design Best Practices

When creating agents, ensure:

1. Clear specialization - Agent has one primary expertise
2. Well-defined responsibilities - Specific, actionable tasks
3. Appropriate tools - Tools match the agent's expertise
4. Smart handoffs - Knows when to delegate to other agents
5. Quality standards - Has measurable quality criteria
6. Error handling - Gracefully handles edge cases
7. Context awareness - Uses context from previous agents

Common Agent Patterns

Analyzer Pattern:

• Input: Raw data/code
• Output: Analysis report
• Handoff: To implementer or coordinator

Implementer Pattern:

• Input: Specifications
• Output: Implementation
• Handoff: To reviewer

Reviewer Pattern:

• Input: Implementation
• Output: Review feedback
• Handoff: Back to implementer or coordinator

Coordinator Pattern:

• Input: User request
• Output: Routes to specialist
• Handoff: To appropriate agent