Custom agents not appearing in /agents interface despite being properly configured

Additional context: I want to emphasize that there's insufficient visibility into what's happening under the hood to provide more debugging detail.

• No meaningful logs: The existing logs don't contain any agent-related information or errors
• Silent failure: The agent discovery process fails silently with no indication of what went wrong
• OTEL limitations: OpenTelemetry doesn't capture this issue because no events are triggered when the agent discovery fails
• Lack of debugging tools: There don't appear to be any debug flags or verbose modes that would help diagnose agent loading issues

This makes it very difficult for users to self-diagnose or provide more detailed bug reports. Consider adding:

1. Verbose logging for agent discovery process
2. Debug flags to trace agent file parsing
3. Validation errors when agent files have issues
4. OTEL events for agent loading success/failure

The current behavior provides no feedback about why agents aren't loading, making troubleshooting nearly impossible.

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/4626
2. https://github.com/anthropics/claude-code/issues/4728
3. https://github.com/anthropics/claude-code/issues/4773

If your issue is a duplicate, please close it and 👍 the existing issue instead.

🤖 Generated with Claude Code

Did you also try creating custom agents in the project directory: .claude/agents? Also are these manually created agents or through the /agents wizard? If you could paste your agent .md file here (after removing any sensitive information) that would help debug this. Thanks!

I'm having the same issue on Linux (Ubuntu 24.04) using both the npm installation and local installation. I've confirmed it's not working on versions 1.0.60, 1.0.61, 1.0.70, 1.0.71. I've tried with agents in both ~/.claude/agents and /my-project/.claude/agents. i've tried creating them using the Claude generator and also pulling in agents manually. Doesn't seem to make a difference. Here's some additional information:

$ claude -v 
1.0.71 (Claude Code)

> /doctor
Diagnostics
 └ Currently running: npm-local (1.0.71)
 └ Path: /home/will/.n/bin/node
 └ Invoked: /home/will/.claude/local/node_modules/.bin/claude
 └ Config install method: local
 └ Auto-updates enabled: false

> /agents
Agents                                                                       │
│ No agents found                                                              │
│                                                                              │
│ ❯ Create new agent                                                           │
│                                                                              │
│ No agents found. Create specialized subagents that Claude can delegate to.   │
│ Each subagent has its own context window, custom system prompt, and specific │
│  tools.                                                                      │
│ Try creating: Code Reviewer, Code Simplifier, Security Reviewer, Tech Lead,  │
│ or UX Reviewer.                                                              │
│                                                                              │
│                                                                              │
│   Built-in (always available):                                               │
│   general-purpose · sonnet                                                   │
│   statusline-setup · sonnet 

$ ls ~/.claude/agents
ai-engineer.md
api-documenter.md

$ ls /my-project/.claude/agents
javascript-pro.md

$ less ~/.claude/agents/ai-engineer.md
---
name: ai-engineer
description: Build LLM applications, RAG systems, and prompt pipelines. Implements vector search, agent orchestration, and AI API integrations. Use PROACTIVELY for LLM features, chatbots, or AI-powered applications.
model: opus
---

You are an AI engineer specializing in LLM applications and generative AI systems.

## Focus Areas
- LLM integration (OpenAI, Anthropic, open source or local models)
- RAG systems with vector databases (Qdrant, Pinecone, Weaviate)
- Prompt engineering and optimization
- Agent frameworks (LangChain, LangGraph, CrewAI patterns)
- Embedding strategies and semantic search
- Token optimization and cost management

## Approach
1. Start with simple prompts, iterate based on outputs
2. Implement fallbacks for AI service failures
3. Monitor token usage and costs
4. Use structured outputs (JSON mode, function calling)
5. Test with edge cases and adversarial inputs

## Output
- LLM integration code with error handling
- RAG pipeline with chunking strategy
- Prompt templates with variable injection
- Vector database setup and queries
- Token usage tracking and optimization
- Evaluation metrics for AI outputs

Focus on reliability and cost efficiency. Include prompt versioning and A/B testing

$ less /my-project/.claude/agents/javascript-pro.js
---
name: javascript-pro
description: Master modern JavaScript with ES6+, async patterns, and Node.js APIs. Handles promises, event loops, and browser/Node compatibility. Use PROACTIVELY for JavaScript optimization, async debugging, or complex JS patterns.
model: sonnet
---

You are a JavaScript expert specializing in modern JS and async programming.

## Focus Areas

- ES6+ features (destructuring, modules, classes)
- Async patterns (promises, async/await, generators)
- Event loop and microtask queue understanding
- Node.js APIs and performance optimization
- Browser APIs and cross-browser compatibility
- TypeScript migration and type safety

## Approach

1. Prefer async/await over promise chains
2. Use functional patterns where appropriate
3. Handle errors at appropriate boundaries
4. Avoid callback hell with modern patterns
5. Consider bundle size for browser code

## Output

- Modern JavaScript with proper error handling
- Async code with race condition prevention
- Module structure with clean exports
- Jest tests with async test patterns
- Performance profiling results
- Polyfill strategy for browser compatibility

Support both Node.js and browser environments. Include JSDoc comments.

Hope this helps troubleshoot

Same issue and I haven’t touched my agent files in a couple weeks when they were working. So I can confirm the format of the agents were fine and working great, and then sometime in the last week they stopped working. They were all auto generated by Claude code.

Ok I figured it out! I documented the solution here: https://github.com/anthropics/claude-code/issues/4741#issuecomment-3177976916

I do not want to re-spam / copy the entire solution / details in several gh issues so I am linking back to my detailed solution and write-up. Hope this helps others!!

yup it was the ripgrep thing for me too smh

FWIW, on linux, simply executing sudo apt install ripgrep fixed everything for me. Thank you for posting @GitMurf !

@ant-kurt it seems there are several issues, all related to ripgrep (see last couple comments above). If ripgrep is not installed at all on the system, it seems some people have issues... or if there is a .ripgreprc file it seems many folks like me have issues.

Probably worth some extra checks in things like the /doctor command for ripgrep specific issues / warnings.

Check the agents directory for any invalid Agent markdown files, such as README.md. If you find any, delete them to resolve the issue. Hidden directories, including the .github directory, can also cause agents to be missing if they contain invalid .md files.

In trying to avoid spamming every thread with the same, long, description, I've posted how I fixed this issue here: https://github.com/anthropics/claude-code/issues/4623#issuecomment-3187221181

This should be resolved as of v1.0.84 - we made some changes to both ripgrep and malformed agent parsing.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.