Verify an agent-skills plugin before you ship or install it

The Stack

Steps

1. 1

   Lay out the package and validate frontmatter + manifest

   Each skill is skills/<name>/SKILL.md with name + description frontmatter, and the plugin is declared in .claude-plugin/marketplace.json. CI checks every SKILL.md parses, its name matches its folder, and the manifest names a plugin. Actually installing it with /plugin install and confirming triggering are fenced.

   mkdir -p skills/blindspot-pass skills/interview-me skills/change-quiz .claude-plugin
   cat > skills/blindspot-pass/SKILL.md <<'EOF'
   ---
   name: blindspot-pass
   description: Surface the user's unknown unknowns before work starts, in an unfamiliar codebase area or domain.
   ---
   # Blindspot pass
   Find what the user does not know they do not know, then help them prompt better.
   EOF
   cat > skills/interview-me/SKILL.md <<'EOF'
   ---
   name: interview-me
   description: Interview the user one question at a time, architecture-changing questions first, to resolve ambiguity before implementation.
   ---
   # Interview me
   Ask one question per turn, biggest blast radius first.
   EOF
   cat > skills/change-quiz/SKILL.md <<'EOF'
   ---
   name: change-quiz
   description: After a working session, report what changed and quiz the user before they merge, so unread changes do not ship.
   ---
   # Change quiz
   Report the change, then a quiz the user must pass to merge.
   EOF
   cat > .claude-plugin/marketplace.json <<'EOF'
   {
     "name": "finding-unknowns-skills",
     "owner": { "name": "Neeeophytee" },
     "plugins": [
       { "name": "finding-unknowns", "source": "./", "description": "Skills for finding your unknowns before they get expensive." }
     ]
   }
   EOF
   ruby -rjson -ryaml -e '
   skills = Dir.glob("skills/*/SKILL.md").sort
   abort "BAD: no SKILL.md files found" if skills.empty?
   ok = 0
   skills.each do |f|
     raw = File.read(f, encoding: "UTF-8")
     abort "BAD: " + f + " does not start with frontmatter" unless raw.start_with?("---")
     fm = YAML.safe_load(raw.split("---")[1])
     abort "BAD: " + f + " missing name" if fm["name"].to_s.empty?
     abort "BAD: " + f + " description too short" if fm["description"].to_s.length < 20
     dir = File.basename(File.dirname(f))
     abort "BAD: " + f + " name does not match its directory " + dir unless fm["name"] == dir
     ok += 1
   end
   mk = JSON.parse(File.read(".claude-plugin/marketplace.json"))
   abort "BAD: marketplace manifest missing name" if mk["name"].to_s.empty?
   plugins = mk["plugins"] || []
   abort "BAD: no named plugin in the marketplace manifest" if plugins.empty? || plugins[0]["name"].to_s.empty?
   puts "skills package OK: " + ok.to_s + " skill(s) valid (frontmatter + dir match); plugin " + plugins[0]["name"] + " in marketplace manifest"
   '

2. 2

   Install and test triggering (the agent step, not checked by CI)

   Publish the repo, then /plugin marketplace add <owner>/<repo> and /plugin install <plugin>@<repo>. Confirm each skill fires when you expect and stays quiet otherwise, that is description tuning, which is fenced. If a skill over-fires, tighten its description and re-validate.