davila7/claude-code-templates · warning

Warning: Could not parse agent file

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.

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
• Could not analyze commands:
• Could not analyze skills:
• Could not analyze subagents:
• Error parsing message line:

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

Appendix: 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)