davila7/claude-code-templates · warning

Warning: Could not parse agent file ${filePath}:

Error message

Warning: Could not parse agent file ${filePath}:

What it means

Parsing a single agent markdown/JSON file failed (frontmatter YAML invalid, missing fields after parse, or read error), so loadAgentFile returns null and that agent is skipped.

Source

Thrown at cli-tool/src/analytics.js:1841

      
      // Use color from frontmatter if available, otherwise generate one
      const color = frontmatter.color ? this.convertColorToHex(frontmatter.color) : this.generateAgentColor(frontmatter.name);
      
      return {
        name: frontmatter.name,
        description: frontmatter.description,
        systemPrompt,
        tools,
        level,
        projectName,
        filePath,
        lastModified: stats.mtime,
        color,
        isActive: true // All loaded agents are considered active
      };
      
    } catch (error) {
      console.warn(chalk.yellow(`Warning: Could not parse agent file ${filePath}:`, error.message));
      return null;
    }
  }

  /**
   * Generate consistent color for agent based on name
   * @param {string} agentName - Name of the agent
   * @returns {string} Hex color code
   */
  generateAgentColor(agentName) {
    // Simple hash function to generate consistent colors
    let hash = 0;
    for (let i = 0; i < agentName.length; i++) {
      const char = agentName.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash; // Convert to 32-bit integer
    }
    

View on GitHub (pinned to a0851ed10c)

Solutions

1. Open the file named in the warning and validate its frontmatter (npx js-yaml or yamllint)
2. Fix YAML syntax: spaces not tabs, matching quotes, closing --- delimiter
3. Remove or rename the broken file so scans skip it cleanly
4. Check for a stray BOM: file starts with \uFEFF before ---

Example fix

# before (broken)
---
name: "My Agent
role: tester
---
# after
---
name: "My Agent"
role: tester
---

const yaml = require('js-yaml');
function validAgentFile(text) {
  const m = text.match(/^---\n([\s\S]*?)\n---/);
  if (!m) return false;
  try { return typeof yaml.load(m[1]) === 'object'; } catch { return false; }
}

function isValidAgent(doc) {
  return !!doc && typeof doc === 'object' && typeof doc.name === 'string';
}

try { return parseAgent(text); }
catch (error) { console.warn(`Could not parse agent file ${filePath}:`, error.message); return null; }

When it happens

Trigger: An agent file in the agents directory with malformed YAML frontmatter (tabs, unclosed quotes), a BOM, or a JSON agent file that isn't valid JSON; the per-file try/catch catches and skips it.

Common situations: Hand-edited agent files with YAML syntax errors; files copied from web with smart quotes; frontmatter delimiter typo (--- vs –––).

Related errors

• Warning: Could not parse YAML frontmatter for ${skillDirName
• Error parsing message line:
• Warning: Could not read agents directory ${agentsDir}:
• Warning: Could not parse ${filename}:
• Could not analyze commands:

AI-assisted analysis of davila7/claude-code-templates@a0851ed10c (2026-08-28). Data as JSON: /api/errors/93e843923c1b1bd7. Report an issue: GitHub.