Summary
Five .github/skills/*/SKILL.md files have frontmatter defects, found while scanning this repo with AgentCompass (skills.name.required, skills.name.charset, skills.name.dirname-match, skills.parses rules) and confirmed manually against the raw files.
Issues
Missing required name field
Per the Agent Skills spec, SKILL.md frontmatter requires a name field. Two files have only description:, no name::
.github/skills/error-recovery-patterns/SKILL.md.github/skills/skillz-integration/SKILL.md
name uses underscores instead of hyphens, and does not match the directory
.github/skills/http-mcp-headers/SKILL.md has name: http_mcp_headers - the spec requires lowercase letters, numbers and hyphens only, and the name must match the parent directory (http-mcp-headers).
Invalid YAML frontmatter (fails to parse)
Two files have a description: value containing an unquoted colon followed by a space partway through the sentence, which is invalid inside a plain YAML scalar (a compliant YAML parser raises "mapping values are not allowed here" at that point):
.github/skills/developer-internals/SKILL.md: description: Internal gh-aw architecture: validation system design, ....github/skills/developer-security/SKILL.md: description: Security best practices for gh-aw workflows and Go code: template injection prevention, ...
I confirmed both fail with PyYAML's safe_load (ScannerError: mapping values are not allowed here); this affects any spec-compliant SKILL.md consumer that parses the frontmatter as YAML, not just this particular scanner.
Fix
Opening a PR that:
- adds the missing
name: fields (matching directory names)
- renames
http_mcp_headers -> http-mcp-headers (confirmed via gh search code that the old name is not referenced anywhere else in the repo)
- quotes the two colon-containing descriptions so they parse as valid YAML
Summary
Five
.github/skills/*/SKILL.mdfiles have frontmatter defects, found while scanning this repo with AgentCompass (skills.name.required,skills.name.charset,skills.name.dirname-match,skills.parsesrules) and confirmed manually against the raw files.Issues
Missing required
namefieldPer the Agent Skills spec, SKILL.md frontmatter requires a
namefield. Two files have onlydescription:, noname::.github/skills/error-recovery-patterns/SKILL.md.github/skills/skillz-integration/SKILL.mdnameuses underscores instead of hyphens, and does not match the directory.github/skills/http-mcp-headers/SKILL.mdhasname: http_mcp_headers- the spec requires lowercase letters, numbers and hyphens only, and the name must match the parent directory (http-mcp-headers).Invalid YAML frontmatter (fails to parse)
Two files have a
description:value containing an unquoted colon followed by a space partway through the sentence, which is invalid inside a plain YAML scalar (a compliant YAML parser raises "mapping values are not allowed here" at that point):.github/skills/developer-internals/SKILL.md:description: Internal gh-aw architecture: validation system design, ....github/skills/developer-security/SKILL.md:description: Security best practices for gh-aw workflows and Go code: template injection prevention, ...I confirmed both fail with PyYAML's
safe_load(ScannerError: mapping values are not allowed here); this affects any spec-compliant SKILL.md consumer that parses the frontmatter as YAML, not just this particular scanner.Fix
Opening a PR that:
name:fields (matching directory names)http_mcp_headers->http-mcp-headers(confirmed viagh search codethat the old name is not referenced anywhere else in the repo)