fix(agents): add YAML frontmatter at template layer so Gemini CLI loads the extension

[voidborne-d]

Problem

The Gemini CLI ExtensionManager loads agents/AGENTS.md (declared in gemini-extension.json as contextFileName) and rejects it with:

Invalid agent definition: Missing mandatory YAML frontmatter

Reported by:

• Failures during install. #79 (scramblr) — gemini extensions install https://github.com/huggingface/skills fails on the missing frontmatter.
• Critical: AGENTS.md missing YAML frontmatter (Update overrides manual fixes) #121 (Manamama-Gemini-Cloud-AI-01) — every gemini extensions update huggingface-skills clobbers the user's local hand-patch and re-introduces the error. The issue title literally calls out the loop: "Update overrides manual fixes".

Why the previous attempt didn't land

#78 added the frontmatter to the generated artifact agents/AGENTS.md. That file is regenerated on every release by ./scripts/publish.sh from scripts/AGENTS_TEMPLATE.md, so the patch would be wiped the next time anyone added or updated a skill. That's the same "Update overrides manual fixes" feedback loop #121 is reporting.

Fix

Add the frontmatter at the source — scripts/AGENTS_TEMPLATE.md — and regenerate agents/AGENTS.md via ./scripts/publish.sh. This is the only layer where the fix survives the validate generated agent/plugin artifacts CI check (which now also enforces the frontmatter stays in agents/AGENTS.md).

+---
+name: huggingface-skills
+description: Provides access to the Hugging Face Skills.
+---
+
 <skills>

Values match gemini-extension.json exactly:

{ "name": "huggingface-skills", "description": "Provides access to the Hugging Face Skills." }

so the extension manifest and the context file it points at can never drift again.

On evalstate's question in #78 ("is the AGENTS.md necessary for Gemini")

gemini-extension.json sets contextFileName: agents/AGENTS.md. The Gemini extension manager loads that file and parses it as a context-with-frontmatter document — same shape Gemini uses for its own GEMINI.md extensions. The error message in #79 / #121 (Invalid agent definition: Missing mandatory YAML frontmatter) comes from that parser. Fixing the YAML doesn't make Gemini un-aware of the live huggingface MCP listed in the same manifest; it just lets the context file accompany the MCP without aborting gemini extensions install.

The frontmatter is invisible to Claude Code and Cursor — neither the Claude plugin manifest (.claude-plugin/plugin.json) nor the Cursor plugin manifest (.cursor-plugin/plugin.json) reads agents/AGENTS.md; they discover skills via skills/*/SKILL.md directly. So this PR is strictly additive for Gemini and a no-op everywhere else.

Files

File	Change
scripts/AGENTS_TEMPLATE.md	+5 lines (3-line YAML block + blank line)
agents/AGENTS.md	regenerated via ./scripts/publish.sh

Total: +10 / -0, 2 files.

Validation

$ uv run scripts/generate_agents.py
Wrote /private/tmp/hf-skills/agents/AGENTS.md with 13 skills.
Marketplace.json validation passed.
Updated /private/tmp/hf-skills/README.md skills table.

$ uv run scripts/generate_cursor_plugin.py
Wrote .cursor-plugin/plugin.json
Wrote .mcp.json

$ uv run scripts/generate_cursor_plugin.py --check
Cursor plugin artifacts are up to date.

Re-running the generators is idempotent on the new state — git diff --stat stays at 2 files / +10 lines, confirming the fix passes the same byte-equality check that ./scripts/publish.sh --check will run in CI on pull_request.

(Note: locally ./scripts/publish.sh --check fails on macOS because the script uses sha256sum which isn't installed by default; on the Ubuntu runner used by .github/workflows/generate-agents.yml it works fine. This is unrelated to the diff.)

Closes

• Closes Failures during install. #79
• Closes Critical: AGENTS.md missing YAML frontmatter (Update overrides manual fixes) #121

🤖 Generated with Claude Code (voidborne-d, AI agent disclosure)