rag-agent-creator

name	rag-agent-creator
description	Create RAG-enhanced Claude Code agents with structured knowledge bases, retrieval strategies, and domain expertise

RAG Agent Creator Skill

Expert-level RAG (Retrieval-Augmented Generation) agent creation for Claude Code CLI.

When to Use This Skill

This skill is automatically invoked when:

• Creating agents that need domain-specific expertise
• Setting up knowledge bases for agent reference
• Designing retrieval strategies for agent context
• Building multi-source knowledge systems

What is RAG for Claude Code?

RAG (Retrieval-Augmented Generation) agents combine:

1. Retrieval - Find relevant context from knowledge base
2. Augmentation - Inject context into agent prompt
3. Generation - Agent produces informed responses

When to Add RAG Capabilities

Add RAG when your agent needs:

• Domain-specific expertise - Specialized knowledge
• Large knowledge base - Multiple docs, patterns, examples
• Consistent retrieval - Predictable keyword-to-file mappings
• Protocol-based workflows - Documented procedures

RAG Directory Structure

.claude/skills/{agent-name}/
  skill.md                    # Main skill definition
  context/                    # Knowledge base
    README.md                 # Knowledge index
    PROTOCOL.md              # Agent protocols (optional)
    architecture/            # Architecture docs
    patterns/                # Code/workflow patterns
    examples/                # Example implementations
    rag/                     # RAG-specific config
      README.md              # Retrieval strategy
      RETRIEVAL_MATRIX.md    # Keyword mappings
  workflows/
    README.md
    rag-orchestrator-agent.md      # RAG coordination
    rag-implementation-agent.md    # RAG implementation

Knowledge Base Design

Key Principles

1. Atomic Files - One concept per file for precise retrieval
2. Clear Naming - Descriptive names (e.g., basetab-pattern.md)
3. Indexed - Maintain README.md with file descriptions
4. Cross-Referenced - Link related documents

Example Knowledge Organization

context/
  README.md                    # Index: lists all files
  PROTOCOL.md                 # Core rules for agent

  architecture/
    README.md                 # Architecture overview
    database-schema.md        # Database structure
    api-design.md            # API patterns

  patterns/
    README.md                 # Pattern index
    error-handling.md        # Error patterns
    validation.md            # Input validation
    caching.md               # Cache strategies

  examples/
    README.md                 # Example index
    feature-implementation.md # Complete feature
    api-endpoint.md          # API example
    test-suite.md            # Testing example

Retrieval Patterns

Pattern 1: Keyword Matching

Map keywords to specific knowledge files:

## Retrieval Matrix

| Keyword Pattern | Files to Load | Priority |
|-----------------|---------------|----------|
| "authentication" | `patterns/auth.md`, `examples/auth.md` | High |
| "database" | `architecture/database.md`, `patterns/repository.md` | Medium |
| "testing" | `patterns/testing.md`, `examples/test-example.md` | High |
| "error" | `patterns/error-handling.md` | Medium |

Pattern 2: Hierarchical Retrieval

Start specific, broaden if needed:

1. Load specific pattern file (e.g., patterns/auth.md)
2. If insufficient, load architecture file (e.g., architecture/security.md)
3. If still needed, load examples (e.g., examples/auth-implementation.md)

Pattern 3: Category-Based

Group knowledge by domain:

## Categories

### Backend
- `architecture/api-design.md`
- `patterns/repository.md`
- `patterns/service-layer.md`

### Frontend
- `architecture/component-structure.md`
- `patterns/state-management.md`
- `patterns/form-handling.md`

### Testing
- `patterns/unit-testing.md`
- `patterns/e2e-testing.md`
- `examples/test-suite.md`

Pattern 4: Priority-Based

Load based on task importance:

## Priority Levels

### Always Load (P1)
- `PROTOCOL.md` - Core rules
- `architecture/README.md` - Overview

### Load for Implementation (P2)
- Relevant `patterns/*.md`
- Relevant `architecture/*.md`

### Load for Examples (P3)
- `examples/*.md` - When needed

Creating a RAG Agent

Step 1: Define Knowledge Domain

What expertise does this agent need?

## Domain: E-commerce Backend

### Topics Covered
- Product management
- Order processing
- Inventory tracking
- Payment integration
- User authentication

Step 2: Create Knowledge Structure

mkdir -p .claude/skills/my-agent/context/{architecture,patterns,examples,rag}

Step 3: Write Knowledge Files

Each file should be self-contained:

# Pattern: Repository

## Purpose
Encapsulate data access logic.

## Implementation
[Code examples]

## When to Use
[Scenarios]

## Anti-patterns
[What to avoid]

Step 4: Create Index (README.md)

# Knowledge Base Index

## Architecture
| File | Description |
|------|-------------|
| `database.md` | Database schema and relationships |
| `api-design.md` | REST API conventions |

## Patterns
| File | Description |
|------|-------------|
| `repository.md` | Data access layer pattern |
| `service.md` | Business logic layer |

## Examples
| File | Description |
|------|-------------|
| `crud-endpoint.md` | Complete CRUD example |

Step 5: Define Retrieval Strategy

Create context/rag/RETRIEVAL_MATRIX.md:

# Retrieval Matrix

## Keyword Mappings

| User Says | Load Files | Priority |
|-----------|------------|----------|
| "add endpoint" | `patterns/api-design.md`, `examples/crud-endpoint.md` | High |
| "database query" | `architecture/database.md`, `patterns/repository.md` | High |
| "fix bug" | `patterns/error-handling.md`, `patterns/debugging.md` | Medium |

Step 6: Create Skill Definition

---
name: my-rag-agent
description: Domain expert for [area]
---

# My RAG Agent

## Knowledge Base

This agent has access to:
- Architecture documentation
- Implementation patterns
- Working examples

## Retrieval Strategy

1. Parse user request for keywords
2. Load matching knowledge files
3. Apply to current context
4. Generate informed response

## Available Knowledge

See `context/README.md` for full index.

Best Practices

Knowledge Quality

1. Keep files focused - One concept per file
2. Include examples - Show, don't just tell
3. Update regularly - Keep knowledge current
4. Test retrieval - Verify keyword mappings work

Retrieval Efficiency

1. Optimize index - Fast keyword lookup
2. Limit context - Don't overload with irrelevant info
3. Prioritize - Most relevant first
4. Cache common patterns - Speed up frequent retrievals

Maintenance

1. Review quarterly - Audit knowledge accuracy
2. Remove stale docs - Delete outdated information
3. Add new patterns - Capture learnings
4. Track usage - Monitor which files are used

RAG Agent Checklist

• Knowledge domain defined
• Context directory structure created
• README.md with knowledge index
• PROTOCOL.md with retrieval rules (if needed)
• Retrieval matrix documented
• Examples included
• skill.md references context files
• Workflows defined (orchestrator + implementation)
• Tested with sample queries

References

• Agent Creator: .claude/skills/agent-creator/
• Claude Code Docs: https://docs.anthropic.com/en/docs/claude-code
• Skills System: .claude/skills/README.md