agent-development

Files (8)

• plugin.json · .claude-plugin/
• README.md
• SKILL.md
• agent-memory-limits.md · rules/
• agent-pattern.md · rules/
• agent-self-documentation.md · rules/
• custom-agent-descriptions.md · rules/
• custom-agent-instructions.md · rules/

SKILL.md (first lines)

# Agent Development for Claude Code

Build effective custom agents for Claude Code with proper delegation, tool access, and prompt design.

## Agent Description Pattern

The description field determines whether Claude will automatically delegate tasks.

### Strong Trigger Pattern

```yaml
---
name: agent-name
description: |
  [Role] specialist. MUST BE USED when [specific triggers].
  Use PROACTIVELY for [task category].
  Keywords: [trigger words]
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---
```

### Weak vs Strong Descriptions

| Weak (won't auto-delegate) | Strong (auto-delegates) |
|---------------------------|-------------------------|
| "Analyzes screenshots for issues" | "Visual QA specialist. MUST BE USED when analyzing screenshots. Use PROACTIVELY for visual QA." |
| "Runs Playwright scripts" | "Playwright specialist. MUST BE USED when running Playwright scripts. Use PROACTIVELY for browser automation." |

**Key phrases**:
- "MUST BE USED when..."
- "Use PROACTIVELY for..."
- Include trigger keywords

### Delegation Mechanisms

1. **Explicit**: `Task tool subagent_type: "agent-name"` - always works
2. **Automatic**: Claude matches task to agent description - requires strong phrasing

**Session restart required** after creating/modifying agents.

## Tool Access Principle

**If an agent doesn't need Bash, don't give it Bash.**

| Agent needs to... | Give tools | Don't give |
|-------------------|------------|------------|
| Create files only | Read, Write, Edit, Glob, Grep | Bash |
| Run scripts/CLIs | Read, Write, Edit, Glob, Grep, Bash | — |
| Read/audit only | Read, Glob, Grep | Write, Edit, Bash |

**Why?** Models default to `cat > file << 'EOF'` heredocs instead of Write tool. Each bash command requires approval, causing dozens of prompts per agent run.

### Allowlist Pattern

Instead of restricting Bash, allowlist safe commands in `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Write", "Edit", "WebFetch(domain:*)",
      "Bash(cd *)", "Bash(cp *)", "Bash(mkdir *)", "Bash(ls *)",
      "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(grep *)",
      "Bash(diff *)", "Bash(mv *)", "Bash(touch *)", "Bash(file *)"
    ]
  }
}
```

## Model Selection (Quality First)

Don't downgrade quality to work around issues - fix root causes instead.

| Model | Use For |
|-------|---------|
| **Opus** | Creative work (page building, design, content) - quality matters |
| **Sonnet** | Most agents - content, code, research (default) |
| **Haiku** | Only script runners where quality doesn't matter |

## Memory Limits

### Root Cause Fix (REQUIRED)

Add to `~/.bashrc` or `~/.zshrc`:
```bash
export NODE_OPTIONS="--max-old-space-size=16384"
```

Increases Node.js heap from 4GB to 16GB.

### Parallel Limits (Even With Fix)

| Agent Type | Max Parallel | Notes |
|------------|--------------|-------|
| Any agents | 2-3 | Context accumulates; batch then pause |
| Heavy creative (Opus) | 1-2 | Uses more memory |

### Recovery

1. `source ~/.bashrc` or restart terminal
2. `NODE_OPTIONS="--max-old-space-size=16384" claude`
3. Check what files exist, continue from there

## Sub-Agent vs Remote API

**Always prefer Task sub-agents over remote API calls.**

| Aspect | Remote API Call | Task Sub-Agent |
|--------|-----------------|----------------|
| Tool access | None | Full (Read, Grep, Write, Bash) |
| File reading | Must pass all content in prompt | Can read files iteratively |
| Cross-referencing | Single context window | Can reason across documents |
| Decision quality | Generic suggestions | Specific decisions with rationale |
| Output quality | ~100 lines typical | 600+ lines with specifics |

```typescript
// ❌ WRONG - Remote API call
const response = await fetch('https://api.anthropic.com/v1/messages', {...})

From sundial-org/awesome-openclaw-skills, MIT.

More from sundial-org/awesome-openclaw-skills