affaan-m/ECC · error

Skill file not found: ${skillFilePath}

Error message

Skill file not found: ${skillFilePath}

What it means

Thrown by ensureSkillExists() in the skill-evolution versioning module when the resolved skill directory does not contain a SKILL.md file. The library refuses to version, snapshot, or roll back a skill it cannot locate, because every other operation reads and writes that file. The thrown message embeds the absolute resolved path so the caller can see exactly where the lookup failed.

Source

Thrown at scripts/lib/skill-evolution/versioning.js:36

    throw new Error('skillPath is required');
  }

  const resolvedPath = path.resolve(skillPath);
  if (path.basename(resolvedPath) === 'SKILL.md') {
    return path.dirname(resolvedPath);
  }

  return resolvedPath;
}

function getSkillFilePath(skillPath) {
  return path.join(normalizeSkillDir(skillPath), 'SKILL.md');
}

function ensureSkillExists(skillPath) {
  const skillFilePath = getSkillFilePath(skillPath);
  if (!fs.existsSync(skillFilePath)) {
    throw new Error(`Skill file not found: ${skillFilePath}`);
  }

  return skillFilePath;
}

function getVersionsDir(skillPath) {
  return path.join(normalizeSkillDir(skillPath), VERSION_DIRECTORY_NAME);
}

function getEvolutionDir(skillPath) {
  return path.join(normalizeSkillDir(skillPath), EVOLUTION_DIRECTORY_NAME);
}

function getEvolutionLogPath(skillPath, logType) {
  if (!EVOLUTION_LOG_TYPES.includes(logType)) {
    throw new Error(`Unknown evolution log type: ${logType}`);
  }

View on GitHub (pinned to 01e15490f0)

Solutions

1. Verify the resolved path printed in the message actually contains a SKILL.md file: ls -la <printedPath>.
2. Pass the skill directory (the folder containing SKILL.md), or the SKILL.md path itself — normalizeSkillDir accepts both forms.
3. If the skill was never created, scaffold it first (create the directory and a SKILL.md with frontmatter) before invoking any versioning API.
4. Check for path typos, wrong working directory (paths are resolved with path.resolve, so relative paths depend on process.cwd()), or case-sensitivity mismatches on case-sensitive filesystems.

Example fix

// before
createVersion('skills/tdd-worflow');  // typo -> Skill file not found

// after
createVersion('skills/tdd-workflow');  // directory that contains SKILL.md

const fs = require('fs');
const path = require('path');

function resolveSkillFile(skillPath) {
  const dir = path.basename(skillPath) === 'SKILL.md' ? path.dirname(skillPath) : skillPath;
  const skillFile = path.join(path.resolve(dir), 'SKILL.md');
  return fs.existsSync(skillFile) ? skillFile : null;
}

// before calling createVersion / rollbackTo / ensureSkillVersioning
const skillFile = resolveSkillFile(skillPath);
if (!skillFile) {
  throw new Error(`Refusing to call versioning API: no SKILL.md at ${skillPath}`);
}

function isSkillDirectory(target) {
  if (typeof target !== 'string' || target.trim().length === 0) return false;
  try {
    const dir = path.basename(target) === 'SKILL.md' ? path.dirname(target) : target;
    return fs.existsSync(path.join(path.resolve(dir), 'SKILL.md'));
  } catch {
    return false;
  }
}

try {
  createVersion(skillPath);
} catch (error) {
  if (/Skill file not found/.test(error.message)) {
    // scaffold the skill or fix the path, then retry or skip
    return;
  }
  throw error;
}

When it happens

Trigger: Calling createVersion(skillPath), rollbackTo(skillPath, ...), ensureSkillVersioning(skillPath), or appendEvolutionRecord(...) with a skillPath that points at a directory missing SKILL.md; passing a path to a file other than SKILL.md whose sibling directory has no SKILL.md; passing a relative path that resolves outside the skills tree; calling versioning APIs before the skill was scaffolded.

Common situations: Typo in the skill directory name; running versioning tooling against a partially-generated skill that has frontmatter only; renaming a skill folder without moving SKILL.md; pointing tooling at the parent skills/ directory instead of the individual skill folder; CI running against a shallow checkout that excluded the skill files.

Related errors

• Multiple ECC repo roots detected: ${uniqueRepoRoots.join(',
• TypeScript compiler not found. Install root dev dependencies
• Missing value for --family
• ${source} is missing the expected catalog marker
• --config-dir must exist and contain a regular sixtytwo.yaml

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/37f44a1de8f06bb2. Report an issue: GitHub.