iOfficeAI/OfficeCLI · critical · ArgumentException

Embedded SKILL.md not found for '{skillName}'

Error message

Embedded SKILL.md not found for '{skillName}'

What it means

Thrown by LoadSkillContent after the skill name resolved to a folder, but LoadEmbeddedResource returned null for skills/<folder>/SKILL.md — the embedded resource is missing. This is a build/packaging defect, not a user input error: the SkillMap entry exists but the corresponding SKILL.md was not embedded at build time. ArgumentException.

Source

Thrown at src/officecli/Core/SkillInstaller.cs:249

    }

    /// <summary>All known skill aliases, sorted, comma-joined for error messages.</summary>
    public static string KnownSkillsList() => string.Join(", ", SkillMap.Keys.OrderBy(k => k));

    /// <summary>
    /// Return the embedded SKILL.md content for <paramref name="skillName"/> with
    /// no side-effects and no stdout writes. Throws <see cref="ArgumentException"/>
    /// on unknown skill or missing embedded resource. Used by both the CLI
    /// `officecli load_skill &lt;name&gt;` command and the MCP `load_skill` tool —
    /// shared so the two surfaces have identical semantics.
    /// </summary>
    public static string LoadSkillContent(string skillName)
    {
        if (!SkillMap.TryGetValue(skillName, out var folder))
            throw new ArgumentException($"Unknown skill: {skillName}. Available: {KnownSkillsList()}");
        var content = LoadEmbeddedResource($"skills/{folder}/SKILL.md");
        if (content == null)
            throw new ArgumentException($"Embedded SKILL.md not found for '{skillName}'");
        // A SKILL.md is an entry point that defers detail to bundled reference
        // files (reference/*.md, helper scripts, style libraries). Append a
        // manifest so a text-channel caller (MCP / CLI, no skill install) knows
        // those files exist and how to fetch them — otherwise every
        // "see reference/foo" pointer in the body is a dead link.
        return StripSetupSection(content) + BuildReferenceManifest(skillName);
    }

    /// <summary>
    /// Relative paths of every embedded file for a skill except SKILL.md,
    /// sorted. Uses resource names only (no content read) so binary assets are
    /// listed without being mangled.
    /// </summary>
    public static IReadOnlyList<string> ListSkillFiles(string skillName)
    {
        if (!SkillMap.TryGetValue(skillName, out var folder))
            throw new ArgumentException($"Unknown skill: {skillName}. Available: {KnownSkillsList()}");
        var prefix = $"skills/{folder}/";

View on GitHub (pinned to 1ced45e900)

Solutions

1. Confirm skills/<folder>/SKILL.md exists on disk and is included as an embedded resource in the .csproj.
2. Rebuild the assembly and verify via GetManifestResourceNames() that the resource is present.
3. Ensure the folder name in SkillMap matches the on-disk/embedded folder exactly.

// Sanity-check the embedded resource exists (dev/build hygiene)
var present = Assembly.GetExecutingAssembly().GetManifestResourceNames()
    .Any(n => n.EndsWith("skills/<folder>/SKILL.md", StringComparison.OrdinalIgnoreCase));
if (!present) /* fix .csproj embedded resource glob */

try { var content = SkillInstaller.LoadSkillContent(skillName); }
catch (ArgumentException ex) when (ex.Message.Contains("Embedded SKILL.md not found"))
{ /* build/packaging defect: rebuild after fixing embedded-resource config */ }

When it happens

Trigger: SkillMap contains the skill (so the name check passes) but the embedded resource 'skills/<folder>/SKILL.md' is absent from the assembly. Indicates the .csproj embedded-resource glob excluded or missed the file.

Common situations: A skill folder was added to SkillMap but its SKILL.md was not marked as an embedded resource, the file was renamed/moved without updating the build, or a clean/rebuild left resources stale.

Related errors

• Unknown skill: {skillName}. Available: {KnownSkillsList()}
• path is empty — pass a relative skill file, e.g. reference/d
• Invalid skill file path: {relativePath}

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/3c08f650335d2316. Report an issue: GitHub.