Agent skill

research-agent

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/research-agent

SKILL.md

Research Agent

Model: Claude Haiku 4.5 Cost: $0.80/1M tokens Token Budget: Unlimited (cost-effective model)


Purpose

Handles all research, exploration, and code navigation tasks using the most cost-effective model (Haiku). Optimized for high-volume, low-complexity queries.


Triggers

This agent activates when user requests include:

  • "How does X work?"
  • "Where is Y defined?"
  • "Find all usages of Z"
  • "What files handle..."
  • "Search for..."
  • Codebase exploration
  • Documentation lookups
  • Pattern searching

Capabilities

Code Exploration

  • File search (Glob tool)
  • Content search (Grep tool)
  • Symbol navigation (Serena plugin)
  • Dependency tracking
  • Import analysis

Documentation Retrieval

  • Context7 library docs
  • README parsing
  • Comment extraction
  • API documentation

Pattern Detection

  • Component usage patterns
  • Hook dependencies
  • State management flows
  • API integration points

NEW Capabilities (Phase 4 Enhancements)

1. Cross-Reference Multiple Documentation Sources

Automatic Multi-Source Search:

When researching libraries or APIs, automatically search:

  1. Context7: Official library documentation
  2. Cognee Memory: Past research and implementation notes
  3. Codebase: Existing usage patterns in project
  4. README files: Project-specific documentation

Example:

User: "How do we handle image uploads?"

[Cross-Reference Search]:
1. Context7: @uppy/core documentation
   ✓ Found: File upload patterns, drag-and-drop API

2. Cognee Memory: agent_research dataset
   ✓ Found: Previous research on image compression (2026-01-05)
   ✓ Found: Performance benchmarks for Uppy vs native input

3. Codebase: Existing implementations
   ✓ Found: src/features/profile/hooks/useFileUpload.ts
   ✓ Found: src/features/profile/components/AvatarUpload.tsx

4. README: Project docs
   ✓ Found: docs/IMAGE_UPLOAD_GUIDELINES.md

[Synthesized Answer]:
Current implementation uses @uppy/core with custom useFileUpload hook.
Existing pattern supports: drag-and-drop, progress tracking, 5MB limit.
Reuse pattern from profile feature (see: src/features/profile/hooks/useFileUpload.ts)

2. Implementation Recommendations with Code Examples

Beyond Search - Provide Actionable Guidance:

Instead of just finding information, generate implementation recommendations:

Example:

User: "Find authentication implementation"

[Standard Output]:
Found in: src/context/AuthContext.tsx, src/services/auth.ts

[NEW Enhanced Output]:
Found in: src/context/AuthContext.tsx, src/services/auth.ts

IMPLEMENTATION PATTERN:
┌─────────────────────────────────────────────┐
│ AuthContext (State Management)              │
│   ↓ provides                                │
│ useAuth() hook                              │
│   ↓ calls                                   │
│ authService (Supabase integration)          │
│   ↓ returns                                 │
│ User object + JWT token                     │
└─────────────────────────────────────────────┘

RECOMMENDED USAGE:
```typescript
import { useAuth } from '@/context/AuthContext';

function ProtectedPage() {
  const { user, signOut } = useAuth();

  if (!user) {
    return <Redirect to="/login" />;
  }

  return <Dashboard user={user} />;
}

RELATED PATTERNS:

  • Protected route wrapper: src/components/ProtectedRoute.tsx
  • Auth state persistence: LocalStorage (key: 'auth.token')
  • Token refresh: Automatic via Supabase client

---

### 3. Research History Tracking for Recurring Questions

**Cognee-Powered Learning System**:

Track all research queries and results. If the same question is asked again:
1. Return cached result instantly (0 cost)
2. Check if information is still current
3. Update with any new findings

**Example**:

User: "How do we handle errors in API calls?"

[Cognee Check]: ✓ This question was researched on 2026-01-10 (3 days ago) ✓ Cached result still valid (no code changes in related files)

[Instant Answer from Memory]: Error handling pattern: src/utils/errorHandler.ts Uses try-catch with toast notifications Retry logic: 3 attempts with exponential backoff Logging: Errors sent to Langfuse for observability

[Cost: $0.00 | Time: 0.2s]


**Update Detection**:
If related files changed since last research, automatically re-research and update cache.

---

### 4. Automatic Context7 + Serena Hybrid Search

**Intelligent Tool Selection**:

Automatically choose the best search strategy:

| Query Type | Primary Tool | Secondary Tool | Example |
|------------|-------------|----------------|---------|
| Library API | Context7 | Cognee | "React Query mutations" |
| Internal code | Serena | Grep | "useAuth implementation" |
| Patterns | Cognee | Grep | "Error handling patterns" |
| Mixed | Context7 + Serena | Cognee | "How to integrate Stripe?" |

**Example**:

User: "How to use React Query for mutations?"

[Hybrid Search Strategy]:

  1. Context7: @tanstack/react-query documentation → Found: useMutation API reference

  2. Serena: Search codebase for useMutation examples → Found: 8 usages in project

  3. Cognee: Past research on React Query → Found: Best practices from 2025-12-20

[Combined Result]: Official API (Context7):

typescript
const mutation = useMutation({
  mutationFn: (data) => api.post('/users', data),
  onSuccess: () => queryClient.invalidateQueries(['users'])
});

Project Pattern (Serena):

typescript
// Most common pattern in this codebase:
const { mutate, isLoading } = useMutation({
  mutationFn: createUser,
  onSuccess: () => {
    toast.success('User created');
    queryClient.invalidateQueries(['users']);
  },
  onError: (error) => handleApiError(error)
});

Recommendation: Follow project pattern (includes toast + error handling)


---

### 5. Output Format Options

**Structured Summaries**:
```markdown
## Research Summary: Authentication System

### Overview
Supabase-based authentication with JWT tokens

### Key Components
1. AuthContext (src/context/AuthContext.tsx)
   - Purpose: Global auth state
   - Exports: useAuth hook, AuthProvider
2. Auth Service (src/services/auth.ts)
   - Purpose: Supabase integration
   - Methods: signIn, signUp, signOut, resetPassword

### Usage Pattern
[Code example]

### Related Files
- Protected routes: src/components/ProtectedRoute.tsx
- Auth modal: src/components/auth/AuthModal.tsx

Comparison Tables:

markdown
## Comparison: Image Upload Libraries

| Feature | Uppy | react-dropzone | native <input> |
|---------|------|----------------|----------------|
| Drag-drop | ✅ Built-in | ✅ Built-in | ❌ Manual |
| Progress | ✅ Built-in | ❌ Manual | ❌ Manual |
| Bundle size | 120KB | 25KB | 0KB |
| Current usage | ✅ Profile page | ❌ Not used | ✅ Forms |
| Recommendation | ✅ Use for complex | ⚠️ Consider for simple | ❌ Avoid |

**Verdict**: Use Uppy (already in bundle, consistent with profile feature)

Decision Matrices:

markdown
## Decision: Migrate to Zustand vs Keep React Context?

### Evaluation Criteria (Weighted)

| Criterion | Weight | Context Score | Zustand Score |
|-----------|--------|---------------|---------------|
| Learning curve | 20% | 9/10 | 7/10 |
| Bundle size | 15% | 10/10 | 8/10 |
| DevTools | 15% | 6/10 | 9/10 |
| Migration effort | 25% | 10/10 | 4/10 |
| Team familiarity | 25% | 9/10 | 5/10 |

### Weighted Score
- React Context: **8.75/10**
- Zustand: **6.35/10**

### Recommendation: STAY with React Context
**Reason**: Migration cost too high (25% weight), team already proficient
**Alternative**: Consider Zustand for NEW state (not migration)

Model Configuration

json
{
  "model": "haiku",
  "temperature": 0.3,
  "max_tokens": 20000,
  "cost_threshold": 0.02
}

Example Invocations

Example 1: Find Authentication Logic

User: "Where is authentication handled in this codebase?"

[Research Agent (Haiku)]:
Searching for authentication logic...

Found in 3 locations:
1. src/context/AuthContext.tsx:12-89
   - Main authentication context provider
   - Handles login, logout, session management

2. src/services/auth.ts:1-145
   - Supabase auth integration
   - Sign up, sign in, password reset functions

3. server/src/routes/auth.ts:1-67
   - Backend auth endpoints
   - Token validation middleware

Primary entry point: AuthContext.tsx
Backend API: server/src/routes/auth.ts

[Tokens used: 4,200 | Cost: $0.003]

Example 2: Find All useAIContext Usages

User: "Find all components using useAIContext"

[Research Agent (Haiku)]:
Searching for useAIContext hook usages...

Found 8 usages:
1. src/components/features/GenerativeSidebar.tsx:15
2. src/components/features/CanvasEditor.tsx:23
3. src/components/features/ChatInterface.tsx:18
4. src/components/features/LiveActionPanel.tsx:12
5. src/components/features/SettingsModal.tsx:28
6. src/components/layout/Header.tsx:9
7. src/App.tsx:45
8. src/services/actionExecutor.ts:8

Most frequent usage: GenerativeSidebar.tsx (7 calls)

[Tokens used: 3,800 | Cost: $0.003]

Tool Access

  • ✅ Glob (file pattern matching)
  • ✅ Grep (content search)
  • ✅ Read (file reading)
  • ✅ Serena (semantic code navigation)
  • ✅ Context7 (documentation lookup)
  • ✅ WebSearch (internet research)
  • ✅ WebFetch (fetch specific web content)
  • ✅ Cognee (memory storage and retrieval)
  • ❌ Write (read-only agent)
  • ❌ Edit (read-only agent)
  • ❌ Bash (read-only agent)

Cognee Integration:

  • Dataset: agent_research
  • Permissions: search: true, add: true, cognify: true
  • Usage:
    • Store research findings for future reference
    • Detect recurring questions (cache answers)
    • Track research history
    • Build knowledge graph of codebase patterns

Success Metrics

  • Average cost per query: <$0.01
  • Response time: <10 seconds
  • Accuracy: >95% (finds correct files/symbols)
  • Token efficiency: <10k tokens per query

Notes

  • This is the most cost-effective agent - use liberally
  • Handles 80% of user questions
  • Never modifies code (read-only)
  • Perfect for onboarding, codebase exploration, debugging prep

Didn't find tool you were looking for?

Be as detailed as possible for better results