Agent Design

Agent Design

Overview

Agent profiles define what an agent can do - its personality, tools, skills, subagents, commands, and integrations. The runtime is architecture-agnostic, supporting both Claude Agent SDK and OpenCode.

AgentProfile Structure

interface AgentProfile {
  // Identity
  id: string;                      // Unique identifier
  name: string;                    // Display name
  description?: string;            // Human-readable description

  // Behavior
  systemPrompt?: string;           // Agent's system prompt
  agentMDFile?: string;            // Memory file content (CLAUDE.md/AGENT.md)

  // Capabilities
  tools?: string[];                // Available tools
  skills?: ClaudeSkill[];          // Skill definitions
  subagents?: ClaudeSubagent[];    // Subagent definitions
  commands?: AgentCommand[];       // Command definitions

  // Integrations
  bundledMCPs?: LocalMcpServer[];  // MCP servers bundled with agent
  externalMCPs?: McpServerConfig[];// External MCP servers

  // Environment
  npmDependencies?: string[];      // npm packages to install
  pipDependencies?: string[];      // pip packages to install
  environmentVariables?: Record<string, string>;
  defaultWorkspaceFiles?: WorkspaceFile[];
}

System Prompt vs Agent Memory File

Both can be used together:

Field	Purpose	Analogy
systemPrompt	Core personality and instructions	The agent's "DNA"
agentMDFile	Contextual memory and project knowledge	The agent's "CLAUDE.md" or "AGENT.md"

Example:

const profile: AgentProfile = {
  id: "code-assistant",
  name: "Code Assistant",

  // Core behavior - who the agent is
  systemPrompt: `You are a senior software engineer. You write clean,
tested code. You explain your reasoning before making changes.`,

  // Project context - what the agent knows about this workspace
  agentMDFile: `# Project: E-commerce API

## Tech Stack
- Node.js + TypeScript
- PostgreSQL + Prisma
- Jest for testing

## Conventions
- Use kebab-case for files
- All API routes in src/routes/
- Run tests before committing`,
};

Tools Configuration

Available tools for Claude Agent SDK:

tools: [
  "Read",    // Read files
  "Write",   // Create new files
  "Edit",    // Edit existing files
  "Bash",    // Execute shell commands
  "Grep",    // Search file contents
  "Glob",    // Find files by pattern
]

Skills

Skills provide specialized knowledge and workflows:

interface ClaudeSkill {
  name: string;              // Skill identifier
  description: string;       // When to use this skill
  skillMd: string;           // Main skill content (markdown)
  supportingFiles?: {        // Additional resources
    relativePath: string;
    content: string;
  }[];
  npmDependencies?: string[];
  pipDependencies?: string[];
}

Example skill:

skills: [{
  name: "api-testing",
  description: "Testing REST APIs with curl and validation",
  skillMd: `# API Testing Skill

## When to Use
Use this skill when testing API endpoints.

## Process
1. Identify endpoint and method
2. Construct curl command
3. Validate response structure
4. Check status codes

## Common Patterns
\`\`\`bash
# GET request
curl -X GET http://localhost:3000/api/users

# POST with JSON
curl -X POST http://localhost:3000/api/users \\
  -H "Content-Type: application/json" \\
  -d '{"name": "John"}'
\`\`\``,
  supportingFiles: [{
    relativePath: "templates/test-script.sh",
    content: "#!/bin/bash\ncurl -v $1"
  }]
}]

Subagents

Subagents handle delegated tasks during a session:

interface ClaudeSubagent {
  name: string;           // Subagent identifier
  description: string;    // When main agent should use this
  prompt: string;         // Subagent's instructions
  model?: string;         // "sonnet" | "opus" | "haiku" | "inherit"
  tools?: string[];       // Allowed tools (subset of main agent)
}

Example:

subagents: [{
  name: "test-writer",
  description: "Delegate test writing to this subagent",
  prompt: `You are a test-writing specialist. Given code, write
comprehensive unit tests. Use Jest. Cover edge cases.`,
  model: "haiku",  // Use faster model for focused task
  tools: ["Read", "Write", "Bash"]
}, {
  name: "code-reviewer",
  description: "Delegate code review to this subagent",
  prompt: `You are a code reviewer. Analyze code for bugs,
security issues, and style problems. Be thorough but constructive.`,
  model: "sonnet",
  tools: ["Read", "Grep"]
}]

Commands

Commands enable the calling application to trigger specific agent workflows by sending command text as a prompt:

interface AgentCommand {
  name: string;     // Command identifier
  prompt: string;   // Instructions executed when command is invoked
}

Example:

commands: [{
  name: "review-pr",
  prompt: `Review the current pull request:

1. Use the code-reviewer subagent to analyze changes
2. Check for security issues using the security-audit skill
3. Verify tests pass by running: npm test
4. Generate a summary with:
   - Overview of changes
   - Issues found (critical/warning/info)
   - Recommendations

Output a structured review report.`
}, {
  name: "deploy-staging",
  prompt: `Deploy to staging environment:

1. Run all tests: npm test
2. Build the project: npm run build
3. Use the deployment MCP server to push to staging
4. Verify deployment with health check
5. Report deployment status`
}]

Invoking commands: The calling application sends the command name as a message:

// In your React app
const { sendMessage } = useMessages(sessionId);
await sendMessage("/review-pr");  // Triggers the review-pr command

MCP Servers

Bundled MCP Servers

MCP servers packaged with the agent:

interface LocalMcpServer {
  name: string;              // Server identifier
  description: string;       // What this server provides
  localProjectPath: string;  // Path to MCP server project
  startCommand: string;      // Command to start server
  installCommand: string;    // Command to install dependencies
}

Example:

bundledMCPs: [{
  name: "github-tools",
  description: "GitHub API integration for PRs, issues, repos",
  localProjectPath: "./mcps/github-server",
  startCommand: "tsx src/index.ts",
  installCommand: "npm install"
}]

External MCP Servers

Pre-existing MCP servers:

externalMCPs: [{
  name: "filesystem",
  command: "npx",
  args: ["-y", "@anthropic-ai/mcp-server-filesystem", "/workspace"]
}]

Workflow Patterns

Pattern 1: Command-Driven Workflows

Define commands that orchestrate skills, subagents, and tools:

commands: [{
  name: "full-feature",
  prompt: `Implement the requested feature:

Phase 1 - Planning:
- Use the architecture skill to design the approach
- Create a task breakdown

Phase 2 - Implementation:
- Implement core functionality
- Use test-writer subagent for unit tests

Phase 3 - Review:
- Use code-reviewer subagent for review
- Address any critical issues

Phase 4 - Finalize:
- Run full test suite
- Update documentation`
}]

Pattern 2: Skill Chains

Skills that reference other skills:

skills: [{
  name: "bug-fix",
  description: "Systematic bug fixing process",
  skillMd: `# Bug Fix Process

1. **Reproduce** - Verify the bug exists
2. **Locate** - Use the debugging skill to find root cause
3. **Fix** - Implement minimal fix
4. **Test** - Use the testing skill to verify
5. **Document** - Update changelog`
}]

Pattern 3: MCP-Enhanced Workflows

Commands that leverage MCP servers:

commands: [{
  name: "sync-docs",
  prompt: `Synchronize documentation:

1. Use the notion-mcp server to fetch latest specs
2. Update local markdown files
3. Use the github-mcp server to create PR
4. Post summary to slack-mcp`
}]

Complete Example

const fullAgentProfile: AgentProfile = {
  id: "full-stack-dev",
  name: "Full Stack Developer",
  description: "Complete development assistant",

  systemPrompt: `You are a senior full-stack developer. You write
clean, tested, documented code. You think before coding.`,

  agentMDFile: `# Project Context
TypeScript monorepo with React frontend and Node.js backend.
Use pnpm. Follow existing patterns.`,

  tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],

  skills: [{
    name: "testing",
    description: "Write and run tests",
    skillMd: "# Testing\nUse Jest. Cover edge cases. Mock externals."
  }],

  subagents: [{
    name: "reviewer",
    description: "Code review",
    prompt: "Review code for bugs and style issues.",
    model: "haiku",
    tools: ["Read", "Grep"]
  }],

  commands: [{
    name: "implement",
    prompt: "Plan, implement, test, and review the feature."
  }],

  bundledMCPs: [{
    name: "db-tools",
    description: "Database operations",
    localProjectPath: "./mcps/db",
    startCommand: "node index.js",
    installCommand: "npm install"
  }],

  npmDependencies: ["lodash", "zod"],
  environmentVariables: {
    NODE_ENV: "development"
  }
};

Related Skills

• overview - Understanding the runtime architecture
• backend-setup - Setting up the backend server
• react-integration - Building React frontends