scripts(skills): drop SKILL_METADATA descriptions, derive from frontmatter#100
Merged
Conversation
… from frontmatter The SKILL_METADATA dict duplicated the `description:` already present in each stable skill's SKILL.md frontmatter, and the two had silently drifted (PR #95 follow-up). _build_stable_entry now calls synthesize_short_description, the same helper used to build agents/openai.yaml short_description. It reads from SKILL.md frontmatter and strips ". Use when ..." / ". Triggers ..." / ". ALWAYS ..." / ". Use this ..." trigger phrases, leaving a clean marketplace blurb for aitools list. Two stable skills had frontmatter descriptions that didn't synthesize cleanly (long single sentence with no trigger marker). Reshaped both to put the blurb in the first sentence followed by a Use when ... trigger list: - databricks-dabs: split "DABs ... for Databricks resources including ..." into "manage DABs. Use when working with Databricks resources including ...". Also dropped em dashes per house style. - databricks-serverless-migration: moved the "Use for ..." trigger list up to the second sentence (as "Use when ..."), kept the rest. Also dropped the unused min_cli_version branch in _build_stable_entry (no stable skill sets it; same dead-plumbing rationale as #95). Co-authored-by: Isaac
Resolves scripts/skills.py conflicts with #91 (unified Codex metadata) and #77 (plugin manifest validation). - Strip `description` field from SKILL_METADATA (point of this PR); keep `plugin_keyword` field because #77 added a validation that consumes it for .claude-plugin/plugin.json keyword coverage checks. - Drop the openai_yaml existence check from `_build_stable_entry`; #91 moved that check into `check_codex_metadata` at validate time. Co-authored-by: Isaac
simonfaltum
changed the title
lennartkats-db
approved these changes
May 28, 2026
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
3 participants
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.
Follow-up to #95 (per comment).
Why
SKILL_METADATAinscripts/skills.pycarried one field per stable skill (description). Each skill already has the samedescription:in itsSKILL.mdfrontmatter, and_build_experimental_entryalready reads from frontmatter viaextract_description_from_skill. Stable skills duplicated, and the dict copy won silently. The two had drifted on main (e.g.databricks-apps: dict said "Databricks Apps development and deployment (evaluates analytics vs synced tables data access)" while frontmatter says "Build apps on Databricks Apps platform. Use when ...").Frontmatter is the natural source of truth: it is what agents see when deciding whether to activate the skill, and the agents/openai.yaml
short_descriptionis already derived from it. Making the manifest description follow the same path closes the gap.Changes
_build_stable_entrynow callssynthesize_short_description(skill_dir)(the same helper used to buildagents/openai.yamlshort_description). It reads from frontmatter and strips the. Use when .../. Use this .../. Triggers .../. ALWAYS ...trigger phrases, leaving a clean marketplace blurb.The
descriptionfield is dropped from theSKILL_METADATAdict. The dict stays (per-skillplugin_keyword) because #77'scheck_plugin_manifestvalidation looks them up to verify.claude-plugin/plugin.jsonkeyword coverage. Only the duplicated description field goes.Diff for the 8 stable skill descriptions in
manifest.json:databricks-appsdatabricks-coredatabricks-dabsdatabricks-jobsdatabricks-lakebasedatabricks-model-servingdatabricks-pipelinesdatabricks-serverless-migrationTwo stable skills had frontmatter descriptions that didn't synthesize cleanly (long single sentence, no trigger marker, so the 200-char length cap kicked in mid-word). Reshaped both to put the blurb in the first sentence followed by
Use when ...:databricks-dabs: splitDABs ... for Databricks resources including ...intomanage DABs. Use when working with Databricks resources including .... Also dropped em dashes per house style.databricks-serverless-migration: moved theUse for ...trigger list up to the second sentence (rephrased asUse when ...), kept the rest.Also dropped the unused
min_cli_versionbranch in_build_stable_entry. No stable skill currently sets it; same dead-plumbing rationale as #95.Experimental skills are untouched, they still use
extract_description_from_skill(verbatim frontmatter, including anyUse when ...triggers). That contract was deliberate and is out of scope for this change.Test plan
python3 scripts/skills.py generateclean.python3 scripts/skills.py validatepasses.manifest.jsonare complete sentences (no mid-word truncation).manifest.jsonunchanged (git diff manifest.jsonshows only stable description deltas).