Enable Registration and Invocation of Custom Project-Specific Agents

Feature Request: Enable Registration and Invocation of Custom Project-Specific Agents

Summary

Allow users to register custom AI agents from their project's .claude/agents/ directory, making them discoverable via the /agents command and directly invocable like built-in agents.

Current Situation

What I'm Doing Now

I've created a comprehensive catalog of 15+ specialized AI agent templates in my project's .claude/agents/ directory to handle domain-specific tasks. Currently, these agents can only be utilized through manual invocation using the Task tool with subagent_type: "general-purpose", requiring copy-pasting of prompts and losing the seamless integration that built-in agents enjoy.

Current Limitations

• Custom agent templates exist only as markdown files with no runtime integration
• The /agents command exclusively shows Claude Code's built-in agents
• No mechanism exists to register or auto-discover project-specific agents
• Teams cannot easily share and standardize specialized workflows through version control
• Significant friction in using custom agents compared to built-in ones

Use Cases

Real-World Examples from My Project

My .claude/agents/ directory contains specialized agents including:

Development Agents:

• frontend-architect - React/UI component design with project design system knowledge
• backend-service-builder - API development following our team's patterns
• database-architect - Schema design with awareness of our data models
• test-automation-engineer - Test creation using our testing standards

Operations Agents:

• security-auditor - Vulnerability analysis with our security requirements
• performance-optimizer - Code optimization based on our performance metrics
• deployment-coordinator - Deployment scripts following our CI/CD pipeline

Process Agents:

• documentation-sync-agent - Keeps documentation in sync with code changes
• requirements-architect - Gathers and structures requirements in our format
• code-reviewer - Reviews code against our team's style guide
• migration-planner - Plans database/API migrations with backward compatibility

Team Collaboration Scenarios

1. Onboarding: New team members could immediately access team-specific agents that encode institutional knowledge
2. Consistency: All developers use the same specialized agents for common tasks
3. Knowledge Sharing: Senior developers can encode expertise into agents for the entire team
4. Domain-Specific Workflows: Industries with specific requirements (healthcare, finance) could maintain compliance-aware agents

Proposed Solution

Core Functionality

1. Auto-discovery: Automatically detect and register agents from .claude/agents/*.md files
2. Command Integration: Custom agents appear in /agents listing with clear differentiation
3. Direct Invocation: Support /agent custom:frontend-architect or similar syntax
4. Project Context: Allow agents to reference project context files (CLAUDE.md, etc.)

Suggested Implementation Approach

# .claude/agents/frontend-architect.yaml
name: frontend-architect
description: "Specialized React/UI development agent for our design system"
version: 1.0.0
tags: [frontend, react, ui]
context:
  - path: ./src/design-system/
  - file: ./docs/ui-guidelines.md
parameters:
  component_type:
    type: string
    enum: [atom, molecule, organism, template]
    default: molecule
prompt: |
  You are a frontend architect specializing in React development...
  [Full prompt content here]

Registration Mechanisms

Option 1: Auto-discovery (Preferred)

• Scan .claude/agents/ on project load
• Hot-reload when agent files change
• Zero configuration required

Option 2: Explicit Registration

// .claude/config.json
{
  "custom_agents": [
    "./agents/frontend-architect.yaml",
    "./agents/backend-service-builder.yaml"
  ]
}

Benefits

For Individual Developers

• Efficiency: Invoke specialized agents as easily as built-in ones
• Consistency: Reuse refined prompts without copy-pasting
• Evolution: Iteratively improve agents based on project needs

For Teams

• Standardization: Ensure consistent approaches across the team
• Knowledge Transfer: Encode best practices and domain knowledge
• Version Control: Track agent evolution alongside code
• Reduced Onboarding Time: New members immediately access team wisdom

For the Claude Code Ecosystem

• Community Sharing: Users could share agent templates for common frameworks/patterns
• Industry Solutions: Specialized agent packs for different domains
• Extended Capabilities: Users can extend Claude Code without waiting for official updates

Implementation Considerations

Security & Sandboxing

• Custom agents should have same permissions as general-purpose agents
• No additional file system access beyond current Claude Code capabilities
• Optional validation/linting of agent definitions

UI/UX Considerations

• Visual Differentiation: Custom agents could appear with a different icon or badge
• Namespace Prevention: Use prefixes (e.g., custom: or project:) to avoid conflicts
• Discovery: Show custom agents in a separate section or with filtering options

Backward Compatibility

• Existing projects without custom agents remain unaffected
• Graceful degradation if agent files are malformed

Alternative Approaches Considered

1. Plugin System: More complex but could enable additional functionality
2. Agent Marketplace: Central repository for sharing agents (future enhancement)
3. UI-Based Agent Creator: Visual tool for creating agents (adds complexity)

Additional Questions for Discussion

1. Should custom agents support chaining/composition with other agents?
2. Would agent versioning be valuable for teams?
3. Should there be limits on the number of custom agents per project?
4. Could agents define custom commands beyond just /agent [name]?
5. Should agents be able to define their own context gathering rules?

Conclusion

This feature would transform Claude Code from a powerful coding assistant into a customizable platform that teams can adapt to their specific needs. By enabling custom agent registration, you would empower users to encode their domain expertise, team standards, and project-specific knowledge into reusable, shareable agents that seamlessly integrate with the Claude Code workflow.

I'm happy to provide additional examples, clarification, or help test any prototype implementations.

---

Environment: Claude Code [v1.0.72]
OS: [Windows 11]
Priority Suggestion: High