/hermes-skill

name: hermes-skill
description: Create, improve, inventory, and audit Claude Code skills. Use when turning a solved workflow into a reusable skill, expanding an existing skill, checking trigger quality, or standardizing a skill pack.
version: 0.1.0
author: OpenAI Codex
license: MIT
metadata:
  category: skilling
  ported_from: NousResearch Hermes Agent
  tags:
    - skills
    - reuse
    - authoring
    - maintenance
  tools:
    - filesystem
    - markdown
    - shell
  maturity: beta

Hermes Skill

Purpose

• Convert repeated workflows into reusable Claude Code skills.
• Keep skills operational rather than descriptive.
• Improve trigger quality so the right skill activates at the right time.
• Audit skill packs for overlap, drift, and incomplete instructions.
• Preserve working patterns after a successful task.

Required Skill Anatomy

• one folder per skill
• one `SKILL.md` file per folder
• YAML frontmatter at the top
• Markdown instructions below the frontmatter
• commands, outputs, and failure handling in the body

Frontmatter Schema For This Package

• `name`
• `description`
• `version`
• `author`
• `license`
• `metadata`

Description Rules

• State what the skill does.
• State when to use it.
• Mention trigger contexts directly.
• Avoid vague phrasing such as "general helper".
• Include important boundaries when the skill is domain-specific.

Naming Rules

• use lowercase letters, digits, and hyphens only
• keep names short and concrete
• prefer operational nouns or verb-noun pairs
• avoid project-specific private jargon unless the package is private
• do not rename a stable public skill casually

Create Workflow

1. Identify a repeated workflow that was just solved. 2. Extract the reusable steps, not the chat narrative. 3. List the exact tools, commands, and files involved. 4. Identify preconditions and failure modes. 5. Write the frontmatter with strong trigger language. 6. Write the body as an operator playbook. 7. Include output contracts where consistency matters. 8. Include examples only when they sharpen execution.

Improve Workflow

1. Read the full skill. 2. Ask what failed or felt ambiguous in actual usage. 3. Tighten the description if triggering was weak. 4. Add missing commands or environment assumptions. 5. Add decision rules where the old version left too much ambiguity. 6. Add failure handling if the skill assumed a happy path. 7. Remove stale instructions and dead commands.

Audit Dimensions

• trigger clarity
• instruction quality
• command accuracy
• line-count sufficiency
• duplication with nearby skills
• presence of decision rules
• presence of output contracts
• presence of verification steps

What Makes A Good Skill

• It reduces repeated thinking.
• It includes exact actions for non-obvious steps.
• It names the right tools and commands.
• It narrows ambiguity without overfitting one repo.
• It handles the common failure path.
• It is faster to use than rediscovering the workflow.

What Makes A Bad Skill

• It repeats generic advice the base model already knows.
• It has weak frontmatter and never triggers.
• It explains philosophy but omits execution.
• It contains stale paths or commands.
• It is so narrow that it only matches one past task.
• It has no failure modes or verification guidance.

Skill Extraction Questions

• What exact problem was solved?
• What sequence of actions worked?
• What tools or connectors were essential?
• What surprised us during execution?
• What constraints would another agent need to know up front?
• What output structure made the result useful?

Standard Sections To Include

• purpose
• activation signals
• inputs
• preflight
• step-by-step procedure
• decision rules
• output contract
• failure modes
• examples
• checklist

Inventory Workflow

1. List all skill folders. 2. Verify that each folder contains `SKILL.md`. 3. Read frontmatter fields. 4. Produce a compact table of name, description, and health. 5. Flag missing or malformed skills.

Overlap Rules

• Two skills may overlap in domain but should differ in operating goal.
• Merge skills if their triggers, commands, and outputs are nearly identical.
• Keep separate skills if one is strategic and the other is procedural.
• Prefer smaller focused skills over one giant omnibus skill.

Updating From Real Usage

• Capture friction immediately after using a skill.
• Update the skill while the failure mode is fresh.
• Preserve examples that encode real mistakes.
• Replace speculative guidance with validated instructions.

Example Improvement Targets

• add missing prereq checks
• tighten "when to use" language
• replace obsolete CLI flags
• add a markdown response template
• split one overloaded skill into two

Audit Output Template

Skill audit report:
- systematic-debugging: Healthy - clear phases, explicit outputs, and verification loop
- old-review-skill: Outdated - stale GitHub CLI commands and no failure handling
- duplicate-debug-skill: Redundant - overlaps heavily with systematic-debugging

Creation Output Template

Created skill: my-new-skill
Path: ~/.claude/skills/my-new-skill/SKILL.md
Why it should trigger: handles repeated workflow for ...
Key sections: purpose, procedure, failure modes, output contract

Decision Rules

• Create a new skill only when the workflow is truly repeatable.
• Improve an existing skill when the use case matches its current mission.
• Split a skill when one body now serves multiple unrelated triggers.
• Keep package-wide conventions consistent across all skills.

Failure Modes

• encoding one conversation instead of the general workflow
• omitting commands because they felt obvious during the original task
• bloating a skill with reference material that belongs elsewhere
• letting frontmatter drift away from actual body content
• failing to update package docs after adding or removing skills

Recovery Moves

• If the skill reads like a