playbook/outfitter-agents/plugins/outfitter/skills/claude-agents/references/discovery.md

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:

# ✅ 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

# Enable debug mode
claude --debug

# Look for:
# "Loading agent: security-reviewer"
# "Agent match score: X"
# "Invoking agent: security-reviewer"

Reload Agents

# 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)