claude_skills_unresolved

claude_skills_unresolved

Error message

Claude skill${missing.length === 1 ? '' : 's'} not found on disk: ${missing.join(', ')}. This is expected for Claude's built-in skills and for plugin-qualified names (plugin:skill), which the SDK resolves itself. If you meant an installed skill, check the name — an unknown name is ignored rather than loaded.

What it means

applyNodeConfig distinguishes declared skills that exist in enabled directories (hard error 605) from names it cannot find on disk (soft warning, code claude_skills_unresolved). Unresolved names are expected for Claude built-in skills and plugin-qualified names (plugin:skill) that the SDK resolves itself; for genuinely unknown names the SDK would silently ignore them, hence the warning.

Source

Thrown at packages/providers/src/claude/provider.ts:563

          const containerNote = skillSearch.isContainer
            ? ' Container workflows cannot use host user-global skills.'
            : '';
          getLog().error(
            { nodeId: nodeConfig.nodeId, unreachable, skillSearch },
            'claude.declared_skills_unreachable'
          );
          throw new Error(
            `Claude skill${unreachable.length === 1 ? '' : 's'} not found in an enabled Claude-native skill directory: ${unreachable.join(', ')}. Install ${unreachable.length === 1 ? 'it' : 'them'} under ${installLocation}.${containerNote}`
          );
        }

        getLog().warn(
          { nodeId: nodeConfig.nodeId, missing, skillSearch },
          'claude.declared_skills_unresolved'
        );
        warnings.push({
          code: 'claude_skills_unresolved',
          message: `Claude skill${missing.length === 1 ? '' : 's'} not found on disk: ${missing.join(', ')}. This is expected for Claude's built-in skills and for plugin-qualified names (plugin:skill), which the SDK resolves itself. If you meant an installed skill, check the name — an unknown name is ignored rather than loaded.`,
        });
      }
    }
  }

  // allowed_tools → tools. `Skill` is re-added only on the workflow path, which
  // is the only one that narrows `options.skills`; adding it for a non-workflow
  // caller would expose the ambient catalog instead of a declared subset.
  const selectsSkills = isWorkflowNode && (nodeConfig.skills?.length ?? 0) > 0;
  if (nodeConfig.allowed_tools !== undefined) {
    options.tools = selectsSkills
      ? [...new Set([...nodeConfig.allowed_tools, 'Skill'])]
      : nodeConfig.allowed_tools;
  }

  // denied_tools → disallowedTools
  if (nodeConfig.denied_tools !== undefined) {
    options.disallowedTools = nodeConfig.denied_tools;

View on GitHub (pinned to 0773b97458)

Solutions

Verify the exact skill name; fix typos for installed skills.
If it is a built-in or plugin skill, no action needed — the SDK resolves it; remove it from the declared list if you want a clean log.
Install the skill under an enabled directory if it was supposed to be a local skill.

Example fix

// before
skills: [code-review, contianerize]
// warning: 'contianerize' not found on disk
// after
skills: [code-review, containerize]

Defensive patterns

Strategy: validation

Validate before calling

const onDisk = new Set(listInstalledSkillNames());
const unknown = (node.skills ?? []).filter(s => !s.includes(':') && !onDisk.has(s));
if (unknown.length) console.warn(`typo? not on disk and not plugin-qualified: ${unknown}`);

Try / catch

const result = await provider.sendQuery(...);
for (const w of result.warnings) {
  if (w.code === 'claude_skills_unresolved') {
    // built-ins/plugin skills are fine; otherwise fix the name
  }
}

Prevention

Copy skill names exactly from the installed skills directory.
Treat warnings with code claude_skills_unresolved as review items, not noise.
Use plugin-qualified names only for skills you know the SDK resolves.

When it happens

Trigger: A node declares a skill name that matches no file on disk: a built-in Claude skill, a `plugin:skill` qualified name, or a plain typo of an installed skill.

Common situations: Using built-in skill names in the YAML; referencing plugin skills that only the SDK resolves; typos like 'code-reviewr'.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/767f12e7eba88777. Report an issue: GitHub.