feat(skill-hygiene): add skill to detect and repair SKILL.md frontmatter#107
Open
jordelmir wants to merge 1 commit into
Open
feat(skill-hygiene): add skill to detect and repair SKILL.md frontmatter#107jordelmir wants to merge 1 commit into
jordelmir wants to merge 1 commit into
Conversation
…+ work around daemon cache MiniMax Code (com.minimax.agent) silently indexes SKILL.md files that lack a YAML frontmatter block, which leaves the skill with an empty description in 'mavis skill ls' and unreachable from the agent tool. Worse, the desktop daemon's in-memory skillIndex is populated only at boot, so an on-disk fix never propagates to 'mavis skill show' until the desktop app restarts. This skill ships: - A stdlib-only Python scanner/repairer that handles both the legacy '# Skill:' header shape and the canonical '--- name/description ---' shape, atomically rewriting affected files. - A reference document describing the cache bug (reverse-engineered from the shipped daemon.js bundle during the 2026-07-04 smoke test) and the three recovery paths: 'mavis skill update --file', launchctl kickstart, and a sandboxed SQLite INSERT. - README entries (English + Chinese) listing the skill under the Community Source column. No third-party runtime dependencies.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
skills/skill-hygiene/— a community skill that audits andrepairs
SKILL.mdfiles used by the MiniMax plugin family(MiniMax Code, OpenCode, Claude Code, Cursor, Codex). It also
documents a workaround for a cache bug in the
MiniMax Codedesktop daemon where
mavis skill showkeeps returning an emptydescriptionfor skills whose YAML frontmatter was added afterthe daemon boot.
The skill ships three artefacts:
SKILL.md— indexable entry point with frontmatter that liststrigger conditions so the agent loads it on the right cues
(
mavis skill lsreturns an empty description,showreturns"", the tool cannot load a skill that is on disk).scripts/fix-skill-frontmatter.py— stdlib-only Pythonscanner/repairer that handles both shapes seen in the wild (the
legacy
# Skill: <Title>header and the canonical--- name: description: ---block). Atomic per-file writes.references/daemon-cache-workaround.md— full reproductionsteps for the daemon cache bug (reverse-engineered from the
shipped
daemon.jsbundle) plus three recovery paths:mavis skill update --file,launchctl kickstart, and asandboxed SQLite
INSERT.README updates add the skill to both the English and Chinese
catalogues under the Community Source column.
Why
secure-by-design-reviewand forty-eight other SKILL.md filesshipped in the desktop bundle use the legacy
# Skill:headershape. The desktop daemon silently indexes them with an empty
descriptionand never refreshes the in-memoryskillIndexwhen the file is fixed on disk, so the only practical recovery is
either a desktop restart (which the CLI correctly refuses because
the user already paid for a working UI) or a well-timed
mavis skill update --file. Without this skill a user has todiscover both facts by hand.
There is no overlap with existing skills —
frontend-devandfullstack-devhelp build things; this one helps repair thecatalogue itself.
Test plan for reviewers
No third-party runtime dependencies — the script uses the Python
3.8+ stdlib only.