Audit: make all SKILL.md frontmatter conform to Agent Skills metadata rules #92

New issue

Closed

opened 2026-07-11 09:18:22 -04:00 by magnus · 0 comments

magnus commented

2026-07-11 09:18:22 -04:00

Owner

Finding

The Agent Skills specification requires metadata to be a map of string keys to string values. It also defines the supported top-level fields as name, description, license, compatibility, metadata, and allowed-tools.

Evidence

A YAML parse of all 61 SKILL.md files found non-string metadata in 34 skills. These are primarily tags arrays and sources arrays. Affected skills: arr-cli, bundles/tailscale, bundles/tailscale/skills/headscale-deploy, bundles/workflow-architect, bundles/workflow-architect/skills/bundle-builder, bundles/workflow-architect/skills/interviewer, bundles/workflow-architect/skills/observer, cli-builder, confluence-cli, data-scientist, epub, forgejo-cli, ghost-cli, github-runner, gutenberg, jellyfin-cli, jira-cli, lastfm, lidarr-cli, nous-branding, open-knowledge-format, openlibrary-cli, opensource-contributions, peertube, prowlarr-cli, software-architecture-analysis, spec-driven-development, systematic-debugging, tempest-cli, tmdb-cli, trakt, transistor, yc-default-alive-calculator, and yc-weekly-growth-compass.

Six skills also use unsupported top-level fields instead of metadata: category in six nested tailscale skills; version in crowdsec, github-runner, langgraph, nous-branding, and traefik; and source_repo in opensource-contributions.

forgejo-cli is worse: its unquoted description contains a colon followed by a space, so its YAML frontmatter does not parse at all.

Acceptance criteria

Convert every metadata value to a string, or move structured data into the Markdown body or a referenced file.
Move category, version, and source_repo into metadata using string values, or remove them.
Quote or otherwise correct forgejo-cli description so a strict YAML parser accepts it.
Add a repository validation check that parses every SKILL.md and enforces the documented field rules.

## Finding The Agent Skills specification requires metadata to be a map of string keys to string values. It also defines the supported top-level fields as name, description, license, compatibility, metadata, and allowed-tools. ## Evidence A YAML parse of all 61 SKILL.md files found non-string metadata in 34 skills. These are primarily tags arrays and sources arrays. Affected skills: arr-cli, bundles/tailscale, bundles/tailscale/skills/headscale-deploy, bundles/workflow-architect, bundles/workflow-architect/skills/bundle-builder, bundles/workflow-architect/skills/interviewer, bundles/workflow-architect/skills/observer, cli-builder, confluence-cli, data-scientist, epub, forgejo-cli, ghost-cli, github-runner, gutenberg, jellyfin-cli, jira-cli, lastfm, lidarr-cli, nous-branding, open-knowledge-format, openlibrary-cli, opensource-contributions, peertube, prowlarr-cli, software-architecture-analysis, spec-driven-development, systematic-debugging, tempest-cli, tmdb-cli, trakt, transistor, yc-default-alive-calculator, and yc-weekly-growth-compass. Six skills also use unsupported top-level fields instead of metadata: category in six nested tailscale skills; version in crowdsec, github-runner, langgraph, nous-branding, and traefik; and source_repo in opensource-contributions. forgejo-cli is worse: its unquoted description contains a colon followed by a space, so its YAML frontmatter does not parse at all. ## Acceptance criteria - Convert every metadata value to a string, or move structured data into the Markdown body or a referenced file. - Move category, version, and source_repo into metadata using string values, or remove them. - Quote or otherwise correct forgejo-cli description so a strict YAML parser accepts it. - Add a repository validation check that parses every SKILL.md and enforces the documented field rules.

magnus referenced this issue from a pull request that will close it,

2026-07-11 09:25:27 -04:00

fix: resolve skill audit findings #97

magnus closed this issue

2026-07-11 09:25:52 -04:00