Fix SKILL.md frontmatter to comply with Agent Skills spec#12304
Fix SKILL.md frontmatter to comply with Agent Skills spec#12304rkondratowicz wants to merge 1 commit intogitbutlerapp:masterfrom
Conversation
- Move version and author from top-level to metadata section - Update inject_version() to handle metadata.version format - Update extract_installed_version_from_content() to parse metadata.version - Update all related tests (13 test cases) This makes the skill compliant with https://agentskills.io/specification where only 'name' and 'description' are valid top-level fields, and custom fields should be nested under the optional 'metadata' field. All 42 unit tests and 2 integration tests pass.
|
@rkondratowicz is attempting to deploy a commit to the GitButler Team on Vercel. A member of the Team first needs to authorize it. |
github-actions
bot
added
rust
There was a problem hiding this comment.
Pull request overview
Updates the GitButler CLI skill to comply with the Agent Skills frontmatter spec by relocating version/author into a metadata section and updating the Rust helpers that inject and read the version accordingly.
Changes:
- Restructured
SKILL.mdfrontmatter to usemetadata.version(andmetadata.author). - Updated version injection logic to write quoted versions into the new frontmatter structure.
- Updated installed-version extraction to locate
metadata.versionand added/updated related tests.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| crates/but/src/command/skill.rs | Updates version injection and installed-version extraction to use metadata.version, plus test updates. |
| crates/but/skill/SKILL.md | Moves version under metadata in the frontmatter to match the spec. |
Comments suppressed due to low confidence (1)
crates/but/src/command/skill.rs:1
- This drops support for previously-installed skills that still have a top-level
version:(old format). That can change behavior (e.g., version checks returningNone) even though the PR description calls this non-breaking. Consider supporting both formats: first trymetadata.version, and if not found, fall back to parsing a top-levelversion:within the frontmatter.
use std::{fmt::Write as _, path::PathBuf};
| // Detect metadata section (no indentation) | ||
| if line.trim() == "metadata:" { |
There was a problem hiding this comment.
Valid YAML like metadata: # comment won’t be recognized because this check requires the trimmed line to equal exactly metadata:. Consider detecting metadata: more robustly (e.g., checking for a metadata: prefix after trimming, and ignoring any trailing inline comment).
| // Detect metadata section (no indentation) | |
| if line.trim() == "metadata:" { | |
| // Detect metadata section (no indentation). Allow inline comments or extra spaces. | |
| let trimmed = line.trim(); | |
| if trimmed.starts_with("metadata:") { |
| // Replace version in metadata section: version: "0.0.0" -> version: "{version}" | ||
| let updated_frontmatter = frontmatter.replace("version: \"0.0.0\"", &format!("version: \"{}\"", version)); |
There was a problem hiding this comment.
Despite the comment, this replaces every version: \"0.0.0\" occurrence within the frontmatter, not specifically metadata.version. If additional version-like fields ever appear in the frontmatter, they could be unintentionally rewritten. Consider using the same metadata-aware scanning approach as extract_installed_version_from_content() to update only the metadata.version entry (and ideally only the first match).
| /// Extract the version from YAML frontmatter content. | ||
| /// Extract the version from YAML frontmatter content (from metadata.version field). | ||
| /// Returns None if the content has no frontmatter or no version entry. | ||
| fn extract_installed_version_from_content(content: &str) -> Option<String> { |
There was a problem hiding this comment.
If you add backward compatibility for the legacy top-level version: format (recommended), add a unit test case that confirms extract_installed_version_from_content() still returns the correct version when version: is present at the top-level (without metadata:).
Byron
added
the
feedback requested
|
Thanks for the suggestion! @krlvi would know best if this change is desirable. Meanwhile, I have put this PR back into draft as it doesn't pass CI and Copilot would probably deserve attention, even if just by discarding its comments. |
🧢 Changes
versionandauthorfields undermetadatasectioninject_version()function to replacemetadata.versioninstead of top-levelversionfieldextract_installed_version_from_content()to parse version from themetadata.versionfield☕️ Reasoning
The current
SKILL.mdfrontmatter uses non-standard top-level fields (versionandauthor) that don't comply with the Agent Skills specification.This change makes the GitButler CLI skill compliant with the Agent Skills spec, which is important for proper integration with AI coding assistants that implement this specification (Claude Code, Cursor, GitHub Copilot, etc.).
Testing:
✅ All 42 unit tests passing
✅ All 2 integration tests passing
✅ Builds successfully with
cargo build -p but --releaseThis is a non-breaking change - the skill functionality remains identical, only the frontmatter structure is updated.