Hermes /learn: author a reusable skill from a source, not by hand

The Stack

Steps

1. 1

   Validate the SKILL.md format contract a /learn skill must meet

   After /learn writes a skill, CI checks the output against the house standard: frontmatter parses with a name, the description is under 60 characters, the canonical sections (Overview, When to use, Steps, Verification) appear in that order, and the slash command derived from the name is valid. The fixture below stands in for a /learn output; the agent actually authoring it is fenced.

   mkdir -p skills/deploy-staging
   cat > skills/deploy-staging/SKILL.md <<'MD'
   ---
   name: deploy-staging
   description: Deploy the app to staging and verify health.
   ---
   
   ## Overview
   Deploy the current branch to the staging server and confirm it is healthy.
   
   ## When to use
   When you need a fresh staging deploy of the current branch.
   
   ## Steps
   1. Push the current branch.
   2. Trigger the staging deploy.
   3. Wait for the health check to pass.
   
   ## Verification
   Confirm the staging health endpoint returns 200.
   MD
   ruby -ryaml -e '
   text = File.read("skills/deploy-staging/SKILL.md")
   parts = text.split("---", 3)
   abort "BAD: no frontmatter block" unless parts.length >= 3
   fm = YAML.safe_load(parts[1]) || {}
   body = parts[2].to_s
   name = fm["name"].to_s
   desc = fm["description"].to_s
   abort "BAD: frontmatter must set a name" if name.empty?
   abort "BAD: frontmatter must set a description" if desc.empty?
   abort "BAD: description must be under 60 chars (house standard)" unless desc.length < 60
   cmd = name.downcase.gsub(" ", "-")
   abort "BAD: derived slash command name is not valid" unless cmd =~ /^[a-z][a-z0-9-]*$/
   required = ["## Overview", "## When to use", "## Steps", "## Verification"]
   positions = required.map { |h| body.index(h) }
   abort "BAD: a required section is missing" if positions.any? { |p| p.nil? }
   abort "BAD: sections are out of house order" unless positions == positions.sort
   puts "skill OK: /" + cmd + ", description under 60 chars, " + required.length.to_s + " sections in house order"
   '

2. 2

   Run /learn for real (the model step, not checked by CI)

   In Hermes, point /learn at a source: a local dir (/learn the REST client in ~/projects/acme-sdk, focus on auth), an online doc (/learn https://docs.example.com/api/quickstart), or a workflow you just walked it through (/learn how I just deployed the staging server). Read the resulting SKILL.md before you trust it, and set terminal.backend docker if the skill contains shell steps. The sourcing and authoring are fenced.