Building Your Personal Skills Library

From One Skill to a Library That Compounds

A single skill is useful. A library of fifty well-organized, high-quality skills is a force multiplier. The difference between a skill that gets used regularly and one that sits idle is not usually quality — it is discoverability. The agent needs to find the right skill at the right moment, and you need to be able to find it when you want to review or update it.

Building a library that compounds means making decisions early about organization, naming, and quality standards, then maintaining them consistently as the library grows. The curator handles the cleanup. The write approval gate handles quality control. What you supply is the initial architecture and the habits that keep it clean.

Naming and Organization Strategy

Skill names become slash commands, so they carry real ergonomic weight. A good naming strategy is one you can apply consistently without thinking, and one that produces slash commands that are memorable and specific enough to type without looking up.

The most reliable approach is verb-noun: describe what the skill does before what it operates on. /submit-pr, /run-tests, /review-code. This makes slash commands feel like actions rather than things, which aligns with how you think about invoking a procedure.

For tool-specific skills, prefix with the tool name: /docker-build, /stripe-refund, /github-pr-workflow. This creates natural namespace separation between skills for different tools and makes the relevant skill discoverable when you type the tool name.

Directory organization within ~/.hermes/skills/ matters for maintenance, not for agent behavior. The agent does not use directory structure for skill discovery — only the frontmatter name and description. Organize directories to serve your own navigation: by tool, by project, by workflow category. A common structure is:

• devops/ — deployment, monitoring, infrastructure skills
• development/ — code review, testing, PR workflows
• tools/ — specific tool integrations
• internal/ — team-specific and project-specific skills

The Skill Quality Checklist

Before promoting a skill from draft to active use, run it through this checklist. A skill that passes all items is ready for reliable production use.

• Description is 60 characters or fewer — count the characters manually or use a character counter. Do not trust the fact that it looks short.
• All four sections are present and in order — When to Use, Procedure, Pitfalls, Verification. Each section has real content, not placeholders.
• Every Procedure step uses a real Hermes tool — no invented commands, no references to capabilities the agent does not have in the target environment.
• At least one Pitfall is documented — even if the first use went perfectly, document what you watched out for or what could go wrong. Empty Pitfalls sections become liabilities later.
• Verification step is concrete — a specific command to run and its expected output, or a specific state to check. "Confirm it worked" is not a verification step.
• Conditional activation is correct for the target environment — if the skill uses Docker toolset features, it has requires_toolsets: [docker]. If it falls back to a simpler procedure, it has fallback_for_toolsets configured correctly.
• Level 0 description passes the relevance test — read the description and ask: would the agent load this skill in the context where it is useful? If not, rewrite the description.

Team Sharing with External Directories

A personal skills library becomes a team asset when you share it. The mechanism is external_dirs in config.yaml. Point every team member's Hermes installation at the same shared repository, and the team's skill library is instantly distributed.

For team libraries to work well at scale, establish a contribution process. Skills added to the shared repository should pass the quality checklist before being merged. A pull request workflow for skill additions — the same workflow you use for code — is the right model. Each skill PR can include the SKILL.md, any reference files, and the /learn command that generated the initial draft if applicable.

Maintain a TEAM-SKILLS.md in the shared repository documenting: what skills are in the library, what they do, what environment they target, and any setup steps required. This index is for humans, not for the agent — it makes the library navigable without reading every SKILL.md individually.

When to Patch vs Rebuild

Skills age. The tool they wrap releases a new version. The procedure changes. The pitfalls you documented are no longer the real pitfalls. Knowing when to patch an existing skill and when to rebuild it from scratch is a practical library maintenance decision.

Patch when: the core procedure is still correct and only specific steps or pitfalls need updating. A new API version that changes one parameter is a patch. A new pitfall discovered in production is a patch. An updated verification command is a patch.

Rebuild when: the underlying tool has changed so substantially that most of the Procedure section is wrong. A major version upgrade that restructures the CLI interface is a rebuild. A complete workflow change (moving from one deployment platform to another) is a rebuild. When more than half the Procedure steps would change, rebuilding is cleaner than patching.

After a rebuild, delete or archive the old skill rather than leaving both versions. Two skills covering the same procedure with different approaches confuse the Level 0 scan — the agent may load both and synthesize a hybrid approach that matches neither.

/suggestions: Letting Hermes Guide Your Learning

As your library grows, identifying which skills to add next becomes harder. The /suggestions command addresses this by analyzing your recent session history and identifying workflow patterns that appear repeatedly but are not yet captured as skills.

When you run /suggestions, the agent reviews recent interactions, looks for recurring multi-step procedures, and proposes skill candidates: "You have run this deployment sequence three times. Would you like to capture it as a skill?" You can accept the suggestion and immediately run /learn on the current-session workflow, or dismiss suggestions that represent one-off tasks.

/suggestions pairs naturally with /learn — together they form a habit loop: run /suggestions periodically to identify what to capture, run /learn to capture it, and let the curator maintain the result over time.

Maintenance Cadence

A skills library requires periodic maintenance even with the curator running. The curator handles lifecycle management but does not improve skill quality — that remains your responsibility.

A sustainable maintenance cadence has three tiers. Weekly: run /suggestions after heavy use sessions, capture any new workflows that appeared, and /reload-skills to ensure you are working with the current library. Monthly: review the curator status output, pin any skills you know you will use infrequently, and patch skills that have become outdated since your last review. Quarterly: run the curator consolidation pass if enabled, audit the Level 0 descriptions across the full library, and check whether any skill directories have grown large enough to benefit from Level 2 reference file extraction.

The goal is a library that stays sharp: accurate descriptions, current procedures, real pitfalls, concrete verification. A library maintained at this cadence compounds in value — each session benefits from skills refined by dozens of previous sessions, and the agent becomes measurably more capable of handling your specific work over time.