Skip to content

fix: skill scanner doesn't handle UTF-8 BOM and SkillScanIssue missing SkillName #1582

Description

@Aaronontheweb

Problem

netclaw skill issues

outputs issues but shows no skill names - just SKILL for every row:

NAME                      KIND                            MESSAGE
------------------------------------------------------------------
SKILL                     MissingFrontmatter              Skill file must start with YAML frontmatter.
SKILL                     InvalidFrontmatter              Skill frontmatter is invalid or unparseable.
SKILL                     InvalidFrontmatter              Skill frontmatter is invalid or unparseable.

3 issue(s)```

Can't tell which skills are broken from this output.

## Root Cause

Two bugs in the scanner:

### 1. UTF-8 BOM breaks frontmatter detection

Most skill files on my machine start with a UTF-8 BOM (`EF BB BF`). `ExtractFrontmatter` checks:

```csharp
if (!content.StartsWith("\---", StringComparison.Ordinal))
    return null;

With a BOM, the content is \uFEFF--- so this fails. Valid frontmatter gets reported as MissingFrontmatter instead of being parsed.

Same check in ParseSkillFile (line 295) and ParseFlatSkillFile (line 342) - all affected.

2. SkillScanIssue never populates SkillName

Every SkillScanIssue creation in SkillScanner.cs omits the SkillName parameter, so it's always null. The CLI fallback (RunIssues line 284) uses Path.GetFileNameWithoutExtension(issue.Path) which returns "SKILL" for every SKILL.md file.

Fix

  1. Strip the BOM in ExtractFrontmatter before checking for ---: content = content.TrimStart('\uFEFF') or use string.TrimStart(new[] { '\uFEFF' }) at the read boundary.
  2. Populate SkillName on all SkillScanIssue records in SkillScanner.cs. The skill name is the parent directory name of the SKILL.md file (Path.GetFileName(Path.GetDirectoryName(filePath))).
  3. Alternatively or additionally, improve the fallback in RunIssues to derive a useful name from the path when SkillName is null.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingskillsSkill loading, handling, authoring, indexing, and evals.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions