Skill Lifecycle Management

+15 Mana ✨
Skills CLI Lifecycle(DOCUMENTATION)

Introduction

Installing a skill is one moment in its life. Over time you will want to list what you have, check for upstream updates, re-scan for security, reset bundled skills you have edited, and uninstall the ones you no longer use. Hermes ships a small set of CLI subcommands for each. The agent itself can also curate skills on your behalf with the skill_manage tool, turning skills into something close to procedural memory.

Key Concepts

  • hermes skills list: Show installed skills with their source identifiers and trust levels.
  • hermes skills check: Compare installed hub skills against upstream and report which ones have changed.
  • hermes skills update: Pull upstream changes for installed hub skills.
  • hermes skills audit: Re-run the security scan on all installed skills.
  • hermes skills reset: Clear a bundled skill's user-modified flag, or restore the upstream version entirely.
  • hermes skills uninstall: Remove a skill from disk.
  • skill_manage tool: An agent-callable tool that lets the model create, edit, and delete skills from inside a session.

Real World Context

A team installs ten skills at the start of a quarter. Three months later they run hermes skills check and see four have upstream updates. They run hermes skills update, two skills now have fresh content. They hermes skills audit to verify nothing got dragged in. Of the remaining six, two are no longer used. hermes skills uninstall for those. The Level 0 index shrinks, the description quality stays high, the agent picks faster.

Deep Dive

The everyday management commands form a small but complete toolkit.

bash
# What is installed and where it came from
hermes skills list
hermes skills list --source hub

# Update flow
hermes skills check           # report drift
hermes skills update          # pull upstream for everything with drift
hermes skills update react    # update one specific skill

# Security re-check
hermes skills audit

# Bundled-skill management
hermes skills reset google-workspace          # take ownership of edits, re-baseline
hermes skills reset google-workspace --restore # restore upstream, discard edits

# Removal
hermes skills uninstall some-skill

A few behaviors worth knowing:

  • Hub provenance lives across updates. When you install from skills-sh/... or openai/skills/..., the source identifier is recorded. check and update use it to re-fetch from the same place.
  • GitHub rate limits. Hub operations hit the GitHub API. Unauthenticated users get 60 requests/hour. Set GITHUB_TOKEN in your environment to raise that to 5,000/hour.
  • Bundled skills sync on hermes update. If you have not edited them, the upstream content lands automatically. Edits flip the skill to user-modified and pause syncing for that one. reset is the escape hatch.

The agent has its own management surface via the skill_manage tool. It can:

text
skill_manage(action='create', name='deploy-runbook', content='---\nname: ...\n')
skill_manage(action='patch',  name='deploy-runbook', old_string='...', new_string='...')
skill_manage(action='edit',   name='deploy-runbook', content='full SKILL.md replacement')
skill_manage(action='delete', name='deploy-runbook')
skill_manage(action='write_file', name='deploy-runbook', file_path='references/notes.md', file_content='...')

The intended use is procedural memory: when the agent completes a non-trivial multi-step task (especially after hitting dead ends and finding the path), it can save the working procedure as a skill. The next time you ask for a similar task, the skill is already there. patch is preferred over edit because it is more token-efficient (only the changed text appears in the tool call).

Common Pitfalls

  1. Skipping audit after pulling updates: New upstream content has not been scanned in your environment yet. hermes skills audit re-runs the scanner on everything.
  2. Using reset without --restore when you want the upstream back: Plain reset just clears the user-modified flag and re-baselines against your current copy. To replace your copy with the bundled version, you need --restore.

Best Practices

  1. Run check periodically: Once a sprint or once a release. Skill maintainers do patch their skills.
  2. Let the agent curate, then review: When the agent uses skill_manage to save a workflow, treat the resulting SKILL.md like a PR. Read it before relying on it.

Summary

  • list, check, update, audit, reset, uninstall cover the lifecycle.
  • Hub provenance is recorded at install and used by check and update.
  • Bundled skills sync automatically until you edit them; reset is the escape hatch.
  • The skill_manage tool lets the agent create and maintain skills on your behalf as procedural memory.

Code Examples

bash
# Typical periodic maintenance pass
hermes skills list
hermes skills check          # see what has changed upstream
hermes skills update         # pull updates
hermes skills audit          # re-scan for security

# Restore a bundled skill you no longer want your edits on
hermes skills reset google-workspace --restore

# Increase GitHub rate limit when doing many hub operations
export GITHUB_TOKEN=ghp_xxx
hermes skills check
✓ Completed