Skip to content

feat(skill-hygiene): add skill to detect and repair SKILL.md frontmatter#107

Open
jordelmir wants to merge 1 commit into
MiniMax-AI:mainfrom
jordelmir:feat/add-skill-hygiene
Open

feat(skill-hygiene): add skill to detect and repair SKILL.md frontmatter#107
jordelmir wants to merge 1 commit into
MiniMax-AI:mainfrom
jordelmir:feat/add-skill-hygiene

Conversation

@jordelmir

Copy link
Copy Markdown

What

Adds skills/skill-hygiene/ — a community skill that audits and
repairs SKILL.md files 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 Code
desktop daemon where mavis skill show keeps returning an empty
description for skills whose YAML frontmatter was added after
the daemon boot.

The skill ships three artefacts:

  • SKILL.md — indexable entry point with frontmatter that lists
    trigger conditions so the agent loads it on the right cues
    (mavis skill ls returns an empty description, show returns
    "", the tool cannot load a skill that is on disk).
  • scripts/fix-skill-frontmatter.py — stdlib-only Python
    scanner/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 reproduction
    steps for the daemon cache bug (reverse-engineered from the
    shipped daemon.js bundle) plus three recovery paths:
    mavis skill update --file, launchctl kickstart, and a
    sandboxed SQLite INSERT.

README updates add the skill to both the English and Chinese
catalogues under the Community Source column.

Why

secure-by-design-review and forty-eight other SKILL.md files
shipped in the desktop bundle use the legacy # Skill: header
shape. The desktop daemon silently indexes them with an empty
description and never refreshes the in-memory skillIndex
when 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 to
discover both facts by hand.

There is no overlap with existing skills — frontend-dev and
fullstack-dev help build things; this one helps repair the
catalogue itself.

Test plan for reviewers

git clone https://github.com/MiniMax-AI/skills.git /tmp/skills-review
cd /tmp/skills-review
git checkout feat/add-skill-hygiene

# 1. Audit-only against any real bundle on the reviewer's machine.
python3 skills/skill-hygiene/scripts/fix-skill-frontmatter.py \
    --dry --skills-dir "$HOME/.minimax/skills"

# 2. Verify the script leaves already-valid files alone.
python3 skills/skill-hygiene/scripts/fix-skill-frontmatter.py \
    --dry --skills-dir ./skills \
    --target frontend-dev

# 3. Render the SKILL.md and confirm the frontmatter passes the
#    strict parser used by the desktop daemon.
head -5 skills/skill-hygiene/SKILL.md

No third-party runtime dependencies — the script uses the Python
3.8+ stdlib only.

…+ 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.
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.

1 participant