Skip to content

fix(plugin): Quote plugin YAML frontmatter so all skills and commands load in strict hosts - #50

Merged
Facundo Santiago (santiagxf) merged 1 commit into
mainfrom
fix/plugin-yaml-frontmatter
Nov 16, 2026
Merged

Facundo Santiago (santiagxf) merged 1 commit into
mainfrom
fix/plugin-yaml-frontmatter

Conversation

@santiagxf

@santiagxf Facundo Santiago (santiagxf) commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Fixes #49.

The problem

Install the plugin in GitHub Copilot CLI and half of it silently doesn't show up. Version 3.1.0 loads 3 of 4 skills and 2 of 6 commands. The rest fail with errors like failed to parse YAML frontmatter or argument-hint must be a string.

Nothing is wrong with the content of those files. The problem is punctuation in the YAML header at the top of each one.

Why it happens

Two ordinary-looking lines break stricter YAML readers:

# A colon-space inside the text. YAML thinks "insights:" starts a new field.
description: Process session summaries to extract insights: where users struggled

# Square brackets at the start. YAML reads this as a list of 3 items, not text.
argument-hint: [gateway resource ID, runtime endpoint, or connection details]

Wrapping the value in quotes tells YAML "this is just text, read it literally":

description: "Process session summaries to extract insights: where users struggled"
argument-hint: "[gateway resource ID, runtime endpoint, or connection details]"

Claude Code's YAML reader is lenient and accepted the unquoted versions, which is why this shipped without anyone noticing. Copilot CLI's is stricter and rejects them.

The fix

1. Added quotes to all ten command and skill files. Only five were actually broken, but the other five are one careless edit away from the same bug — adding a colon to a description would do it. Quoting all of them closes that off.

No wording changed. Every description and hint parses back byte-identical to what shipped, bodies included. The diff is quote characters and nothing else.

2. Added a CI check (.github/scripts/check-plugin.py + .github/workflows/plugin.yml) so this can't come back. It verifies that:

  • every command and skill file parses under a strict YAML reader, and that each value is text rather than a list;
  • the values are quoted, which is what actually guarantees the above — whether an unquoted line happens to work depends on which agent is reading it;
  • all five manifests agree on the version number and list the same files, and every file they list exists.

It needs no extra dependencies to run locally. CI installs PyYAML so it can also do the strict parse.

3. Bumped the version to 3.1.1 in all five manifests: .claude-plugin/plugin.json, .claude-plugin/marketplace.json, .cursor-plugin/plugin.json, .github/plugin/plugin.json, and gemini-extension.json.

Why the CI check matters here

PR #38 rewrites all ten of these files, and it still has the bracket problem in three of them. Running the new check against that branch today:

commands/discover.md: strict YAML parse failed
commands/build.md:    strict YAML parse failed
commands/feedback.md: strict YAML parse failed

So fixing the files alone would be undone as soon as #38 lands. The CI check is what turns that into a failed build instead of another quietly broken release.

Verification

  • Ran the check against 8cba384, the released commit the issue names: it reports all five failures, at the same line and column numbers the reporter saw in Copilot CLI.
  • Ran it against this branch: passes.
  • Deliberately broke things to confirm it catches them: a version bumped in only one manifest, manifests listing different files, a manifest pointing at a file that doesn't exist, and a skill whose name doesn't match its folder.
  • The Gemini extension (commands/aigateway/*.toml) was already quoted correctly and is unaffected.

Not verified: the built plugin was not installed in Copilot CLI itself, so the loader behaviour is taken from the issue report. The error positions line up exactly with a strict parser, which is good corroboration.

🤖 Generated with Claude Code

Version 3.1.0 shipped with five of its ten commands and skills unloadable
in GitHub Copilot CLI. Nothing was wrong with the content; the frontmatter
just leaned on a lenient YAML reader. An unquoted ": " inside a description
aborts a strict parse, and an argument-hint starting with "[" is read as a
flow sequence, so the host gets a list where it wants a string. Claude Code
accepted all of it, which is how the break reached a release unnoticed.

Quote description, argument-hint, and version across all ten files, not
just the five that failed, so the next edit cannot reintroduce it. The
values are untouched: every one parses back byte-identical to what shipped.

Add .github/scripts/check-plugin.py and the workflow that runs it, because
the quoting is a fix with a short shelf life on its own. The script enforces
quoting, which makes a value a string under every YAML implementation
whatever it contains, and layers a strict parse on top when PyYAML is
installed, the way migrate-apim validate treats jsonschema. It also checks
that all five manifests publish the same version and the same file lists,
which a bump that misses one would otherwise get wrong silently.

Bump to 3.1.1 across those five manifests.

Fixes #49

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@santiagxf Facundo Santiago (santiagxf) changed the title Quote plugin YAML frontmatter so all skills and commands load in strict hosts fix(plugin): Quote plugin YAML frontmatter so all skills and commands load in strict hosts Nov 16, 2026

@paulyuk Paul Yuknewicz (paulyuk) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I never understood this about quotes in frontmatter.

@santiagxf
Facundo Santiago (santiagxf) merged commit 291d0b0 into main Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Plugin: Quote YAML frontmatter strings so all skills and commands load in GitHub Copilot CLI

2 participants