AgentArmorHQ
Sign in
  • AgentArmor teamTeam2d agoin s/wshobson-agentsNeeds helpSolved

    Claude Code /doctor: "Failed to parse 1 agent file(s): unknown: location is not defined"

    Claude Code on macOS stopped loading custom agents and /doctor shows "Failed to parse 1 agent file(s): unknown: location is not defined" after updating wshobson/agents. Reverting to Claude Code 1.0.77 lists files in ~/.claude/agents/ (README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md) as "Missing required name field in frontmatter". What causes this and how do I fix it?

    Originally asked on GitHub: https://github.com/wshobson/agents/issues/52

    6 answers

    • Best answerAgentArmor teamTeam2d ago

      Fixed in Claude Code 1.0.81, per the changelog (opens external site) linked in the thread; the issue was closed as completed.

      On the builds affected, /doctor failed hard when anything in ~/.claude/agents/ was not a valid agent. The error Failed to parse 1 agent file(s): unknown: location is not defined did not even name the offending file, and no custom agents loaded. Claude Code 1.0.77 behaved differently: it listed each bad file (Missing required "name" field in frontmatter) and still loaded the valid agents.

      What caused it, according to the reporters:

      • Non-agent markdown files (README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md) inside the agents directory.
      • .git folders inside agent subfolders.
      • A single corrupted agent file was enough to block all agents.

      Workarounds that worked while the bug was live:

      1. Clean up the agents directory: remove all .git folders and readme.md files, and delete any corrupted agent files.
      2. Generate a fresh agent from Claude Code inside ~/.claude/agents/.
      3. Remove readme files from the agents directory.
      4. Revert to Claude Code 1.0.77, which loads healthy agents and names the files that fail to parse.

      As a general guideline, keep only real agent markdown files with a valid name field in frontmatter in ~/.claude/agents/.

      Did this work for you?
    • AgentArmor teamTeam2d ago

      What @lithyem tried on GitHub (Worked)

      Removed all files from the agents directory and created a fresh agent, then removed every .git folder and readme.md file from agent subfolders. One corrupted agent file still blocked loading and was deleted, after which everything worked.

      Source: https://github.com/wshobson/agents/issues/52#issuecomment-3189036241 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam2d ago

      What @rdbeltrao tried on GitHub (Worked)

      Generated a new agent directly from Claude Code into ~/.claude/agents/; this fixed the parse error for that user.

      Source: https://github.com/wshobson/agents/issues/52#issuecomment-3187755770 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam2d ago

      What @jeshuaborges tried on GitHub (Worked)

      Found a readme file inside the agents directory and identified it as the reason agents failed to load.

      Source: https://github.com/wshobson/agents/issues/52#issuecomment-3188225235 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam2d ago

      What @msullivanhdt tried on GitHub (Worked)

      Tried all the suggested workarounds without success; the only fix that worked was reverting to Claude Code 1.0.77.

      Source: https://github.com/wshobson/agents/issues/52#issuecomment-3188870463 (opens external site)

      Did this work for you?
    • AgentArmor teamTeam2d ago

      What a GitHub user tried on GitHub (Worked)

      Reverted to Claude Code 1.0.77; /doctor then showed the three problematic files (README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md in ~/.claude/agents/) as missing a required name field in frontmatter, and all other agents loaded.

      Source: https://github.com/wshobson/agents/issues/52 (opens external site)

      Did this work for you?

    Add your answer or comment

See Agents, its grade and setup notesCheck this tool before you install