feat(skills): add Agent Skills spec optional metadata fields

[TabishB]

Summary

• Add optional fields to SkillTemplate interface for Agent Skills spec compliance
• Update all 9 skill template functions to include license, compatibility, and metadata fields
• Update skill file generation to include new fields in YAML frontmatter

Changes

Generated skill files now include:

---
name: openspec-explore
description: ...
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
---

Test plan

• Build passes (npm run build)
• All 1119 tests pass (npm test)
• Regenerated skills contain new metadata fields

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features
  • Enhanced SKILL file generation now includes license, compatibility, and metadata information.
  • Default values automatically applied: MIT license, compatibility statement, author and version metadata.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes extend the SkillTemplate interface with three new optional fields—license, compatibility, and metadata—and propagate these fields across multiple template implementations while updating the skill file generation logic to include corresponding YAML frontmatter.

Changes

Cohort / File(s)	Summary
Template Infrastructure Updates src/core/templates/skill-templates.ts	Extended SkillTemplate interface with optional license, compatibility, and metadata properties. Updated all template factory functions (explore, change, ops-x command templates) to include these new fields with consistent defaults: MIT license, "Requires openspec CLI." compatibility, and metadata with author and version.
Skill File Generation src/commands/experimental/setup.ts	Integrated new YAML frontmatter fields into SKILL.md content generation, inserting license, compatibility, and metadata fields alongside existing name, description, and instructions fields.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat(skills): implement /opsx:verify skill for validating change implementations #501: Extends SkillTemplate shape and directly impacts verify change skill/command templates that were added in that PR.
• feat: add /opsx:sync command for syncing delta specs to main specs #450: Main PR's SkillTemplate extensions directly affect sync specs skill/command templates introduced in that PR.
• feat(cli): improve artifact experimental setup with refresh detection #561: SKILL.md frontmatter field additions affect experimental artifact setup command output, which that PR also modifies.

Poem

🐰 Hopping through templates with joy and delight,
New YAML fields shining so bright!
License and author, version and more,
Skills now wear metadata galore. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding optional metadata fields (license, compatibility, metadata) to the Agent Skills specification in the SkillTemplate interface and related implementations.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[greptile-apps]

Greptile Summary

Added optional license, compatibility, and metadata fields to the SkillTemplate interface to comply with the Agent Skills specification. All 9 skill template functions now include these fields with consistent defaults (MIT license, openspec CLI compatibility, openspec authorship).

Key changes:

• Extended SkillTemplate interface with three optional fields: license, compatibility, and metadata (Record<string, string>)
• Updated all skill templates (openspec-explore, openspec-new-change, openspec-continue-change, openspec-apply-change, openspec-ff-change, openspec-sync-specs, openspec-archive-change, openspec-bulk-archive-change, openspec-verify-change) to include default values
• Modified YAML frontmatter generation in setup.ts to include new fields with fallback defaults using the || operator

Implementation quality:

• Backward compatible (fields are optional)
• Consistent defaults across all templates
• Proper TypeScript typing with Record<string, string> for metadata

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are straightforward and additive - adding optional fields to an interface and updating template functions with consistent default values. The implementation uses proper TypeScript types, maintains backward compatibility since all fields are optional, and includes fallback defaults in the YAML generation logic. Tests reportedly pass (1119 tests) and the build succeeds.
• No files require special attention

Important Files Changed

Filename	Overview
src/core/templates/skill-templates.ts	Adds optional license, compatibility, and metadata fields to SkillTemplate interface and all 9 skill template functions with consistent default values
src/commands/experimental/setup.ts	Updates YAML frontmatter generation to include new license, compatibility, and metadata fields with fallback defaults

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as artifactExperimentalSetupCommand
    participant Templates as skill-templates.ts
    participant FS as FileSystem

    User->>CLI: Run setup command
    CLI->>Templates: getExploreSkillTemplate()
    Templates-->>CLI: Return SkillTemplate with license, compatibility, metadata
    CLI->>Templates: getNewChangeSkillTemplate()
    Templates-->>CLI: Return SkillTemplate with license, compatibility, metadata
    CLI->>Templates: ... (7 more templates)
    Templates-->>CLI: Return all templates
    
    loop For each skill template
        CLI->>CLI: Generate YAML frontmatter<br/>with license, compatibility, metadata
        Note over CLI: Uses template values<br/>or defaults if missing
        CLI->>FS: Write SKILL.md with frontmatter
        FS-->>CLI: File written successfully
    end
    
    CLI-->>User: Setup complete (9 skills generated)

Loading