95 lines
2.3 KiB
Markdown
95 lines
2.3 KiB
Markdown
# Agent Discovery & Loading
|
|
|
|
How Claude finds and loads agents.
|
|
|
|
## Loading Order
|
|
|
|
1. **Scan directories:**
|
|
- Plugin agents: `<plugin>/agents/*.md`
|
|
- Project agents: `<project>/agents/*.md`
|
|
- Personal agents: `~/.claude/agents/*.md`
|
|
|
|
2. **Parse frontmatter:**
|
|
- Validate YAML syntax
|
|
- Extract description, tools
|
|
- Build agent registry
|
|
|
|
3. **Priority resolution:**
|
|
- Personal > Project > Plugin
|
|
- Same name: higher priority wins
|
|
|
|
## Discovery Process
|
|
|
|
**How Claude matches agents to requests:**
|
|
|
|
1. **Parse user intent** — identify task type, extract keywords
|
|
2. **Match descriptions** — compare request with agent descriptions
|
|
3. **Rank by relevance** — score matches, consider tool requirements
|
|
4. **Select best match** — invoke via Task tool
|
|
|
|
## Naming for Discovery
|
|
|
|
Good descriptions contain keywords users naturally say:
|
|
|
|
```yaml
|
|
# ✅ Good: Keywords + examples
|
|
description: |
|
|
React testing specialist using Jest and React Testing Library.
|
|
Triggers on component testing, Jest test creation, or RTL usage.
|
|
|
|
<example>
|
|
Context: User wants to test a React component
|
|
user: "Write tests for the UserProfile component"
|
|
assistant: "I'll use the react-tester agent to create tests."
|
|
</example>
|
|
|
|
# Keywords: react, testing, jest, react testing library
|
|
# Triggers: "test react component", "jest tests", "RTL"
|
|
|
|
# ❌ Bad: Vague, no examples
|
|
description: Testing helper
|
|
```
|
|
|
|
## Trigger Keywords
|
|
|
|
Include terms users naturally say:
|
|
|
|
- **Action verbs:** review, check, audit, analyze, test, build, fix
|
|
- **Domain terms:** security, performance, auth, API, database
|
|
- **Technologies:** GraphQL, JWT, PostgreSQL, React, TypeScript
|
|
|
|
## Debug Discovery
|
|
|
|
```bash
|
|
# Enable debug mode
|
|
claude --debug
|
|
|
|
# Look for:
|
|
# "Loading agent: security-reviewer"
|
|
# "Agent match score: X"
|
|
# "Invoking agent: security-reviewer"
|
|
```
|
|
|
|
## Reload Agents
|
|
|
|
```bash
|
|
# Changes detected automatically
|
|
# Force reload:
|
|
/clear
|
|
|
|
# Or restart Claude Code
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
**Agent not being invoked:**
|
|
- Check file location: `agents/agent-name.md`
|
|
- Validate YAML frontmatter syntax
|
|
- Make description more specific with trigger keywords
|
|
- Add example conversations
|
|
|
|
**Wrong agent invoked:**
|
|
- Make description more distinct
|
|
- Add specific trigger keywords
|
|
- Include negative examples (what NOT to use it for)
|