Skip to content

SKILL.md frontmatter defects: missing name field, invalid name charset, and unparseable YAML in descriptions #51445

Closed

Description

@YoavLax

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

Activity

  1. locked and limited conversation to collaborators on Aug 8, 2026
  2. unlocked this conversation on Aug 8, 2026
  3. YoavLax commented on Aug 8, 2026

    @YoavLax
    Author

    Fix branch (PR creation is restricted on this repo for external contributors, so linking directly): https://github.com/YoavLax/gh-aw/tree/fix/skill-frontmatter-issues

    Compare/diff view: main...YoavLax:gh-aw:fix/skill-frontmatter-issues

    Feel free to cherry-pick the commit or open the PR yourselves from that branch.

  4. locked and limited conversation to collaborators on Aug 8, 2026
  5. unlocked this conversation on Aug 8, 2026
  6. linked a pull request that will close this issueFix invalid SKILL.md frontmatter metadata #51457on Aug 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions