Agent Loading Failure After Version Upgrade to 1.0.80

It seems like if ANY agent file fails to load then ALL agent files will fail to load even if they are valid.

I had a few agent files that were missing frontmatters and a README.md in my ~/.claude/agents folder that cause the whole agent loading subsystem to fail

Investigation Report: Agent Loading Cascade Failure

Summary

I've conducted a thorough investigation into the agent loading failure issue. The problem is confirmed: when ANY agent file fails to load, ALL agent files fail to load, even if they are otherwise valid.

Root Cause Analysis

The issue appears to stem from a fail-fast behavior in the agent loading mechanism introduced between versions 1.0.77 and 1.0.88. This is most likely caused by one of the following patterns:

1. Promise.all() Anti-pattern: The agent loader likely uses Promise.all() to load all agents simultaneously. When any single promise rejects (due to invalid frontmatter, missing name field, etc.), the entire Promise.all() rejects, causing all agents to fail.

1. Synchronous validation with early exit: The loader may be iterating through agent files synchronously and exiting immediately upon encountering the first error, without attempting to load remaining valid agents.

1. Shared state corruption: A failed agent load may be corrupting shared state that prevents subsequent agents from loading properly.

Technical Details

Based on the error messages and behavior:

• Agent files are loaded from ~/.claude/agents/ directory
• Each agent requires valid YAML frontmatter with at minimum a name field
• The loading process lacks error isolation between individual agent files
• No graceful degradation is implemented for partial agent loading

Proposed Solution

The agent loader should be refactored to:

1. Implement individual error handling for each agent file:

// Instead of:
const agents = await Promise.all(agentFiles.map(loadAgent));

// Use:
const agents = await Promise.allSettled(agentFiles.map(loadAgent));
const loadedAgents = agents
  .filter(result => result.status === 'fulfilled')
  .map(result => result.value);
const failedAgents = agents
  .filter(result => result.status === 'rejected')
  .map((result, index) => ({ file: agentFiles[index], error: result.reason }));

1. Log warnings for failed agents without blocking others:

failedAgents.forEach(({ file, error }) => {
  console.warn(`Failed to load agent from ${file}: ${error.message}`);
});

1. Return successfully loaded agents even if some fail
2. Provide diagnostic information about which specific agents failed and why

Temporary Workaround

Until a fix is released, users can:

1. Validate all agent files have proper YAML frontmatter with required fields:

# Check all agent files for valid frontmatter
for file in ~/.claude/agents/**/*.md; do
  echo "Checking: $file"
  head -10 "$file" | grep -E "^name:" || echo "  ⚠️  Missing 'name' field"
done

1. Remove or fix problematic agent files:

# Backup agents directory first
cp -r ~/.claude/agents ~/.claude/agents.backup

# Then fix or remove problematic files

1. Create a minimal agent file template for reference:

---
name: agent-name
description: Agent description
tools: Read, Write
---

Agent instructions here...

Impact Assessment

• Severity: High - Complete loss of agent functionality when any single agent has issues
• Affected Versions: 1.0.77 - 1.0.88 (at minimum)
• User Impact: Unable to use ANY agents if even one has invalid metadata
• Workaround Available: Yes, but requires manual intervention

Recommended Priority

This should be treated as a high-priority bug as it:

1. Breaks existing functionality for users with custom agents
2. Provides poor user experience (all-or-nothing failure)
3. Lacks clear error messaging about which specific agent is problematic
4. Affects a core feature of Claude Code

The fix should be relatively straightforward - implementing proper error isolation in the agent loading pipeline.

Thanks for the report. Fix coming in next version

If this is the cause, it also breaks having any documentation or supporting files in ~/.claude/agents/*/ if having any .md file not having agent metadata breaks it.

i'm fairly certain i'm experiencing this as well since the update today. Claude is telling me there's issues with the task agent finding any custom agents.

After removing the custom "tools: " block in my agent he started working again, hope this helps someone

Same issue here, and newly created agents by Claude, don't show up either, effectively cant use any subagents.
Im on a Mac.

In my setup, I have an agent that relies on several supporting files and scripts, which I organize within a nested folder structure under agents/. However, this approach currently breaks functionality. It would be beneficial to support nested structures like this, otherwise, we’re forced to keep agent-related files scattered elsewhere in the project, which is tedious and challenging to maintain.eg:

claude-config/agents/
├── doc-gen/                              # Documentation Generation System
│   ├── data-structures/                  # Schema Definitions
│   │   ├── FileListConfiguration.md      # File selection configuration schema
│   │   ├── LanguageContext.md           # Language-specific context schema
│   │   ├── ProgressTracking.md          # Progress tracking data structures
│   │   ├── WorkResponse.md              # Agent response format schema
│   │   └── WorkTask.md                  # Agent task input schema
│   ├── supported-languages/             # Language-Specific Support
│   │   └── dart/                        # Dart Language Support
│   │       ├── exclude-list.md          # Files/patterns to exclude from documentation
│   │       └── language-context.md      # Dart documentation conventions and guidelines
│   ├── documentation-setup.sh           # Setup script for documentation generation
│   ├── documentation-writer-agent.md    # Main documentation generation agent
│   └── generate-file-list.sh           # Utility script for file discovery
└── other-agents.md                      # Placeholder for additional agents

In my setup, I have an agent that relies on several supporting files and scripts, which I organize within a nested folder structure under agents/. However, this approach currently breaks functionality. It would be beneficial to support nested structures like this, otherwise, we’re forced to keep agent-related files scattered elsewhere in the project, which is tedious and challenging to maintain.eg:

This is my setup as well, nice to see someone else thinking along the same lines :)

Apologies for the regression. Fix will be out with the next release

---

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/5758
2. https://github.com/anthropics/claude-code/issues/5763
3. https://github.com/anthropics/claude-code/issues/5748

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This issue has been automatically closed as a duplicate of #5758.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

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.