Building Your Personal Library

Naming Conventions That Scale

Skill names are invocation commands. A name that seems clear for a single skill becomes ambiguous when the library grows past a dozen. Two conventions keep it navigable at any size:

Verb-noun slugs. Names like deploy-staging, review-pr, and backup-check describe actions rather than topics. Compare these to topic nouns like deployment, git, or checks — the verb-noun form tells you what the skill does when invoked, not just what area it covers. The difference matters most in the / menu, where you scan under time pressure.

Scope prefixes for coexisting variants. When a personal version and a team version of the same workflow both exist, a prefix resolves the ambiguity: team-deploy and deploy coexist without collision. Generic names without scope context also collide with community skills: review is too broad; review-pr is specific enough to stand alone.

Location Strategy

Claude Code and Hermes each support multiple skill locations with different scopes. Choose based on who needs access and whether the skill belongs in version control:

• Claude Code ~/.claude/skills/ — personal skills available across all projects on this machine, but not in Cowork or cloud sessions. Back this directory up with a dotfiles repo or a dedicated ~/.claude git repository.
• Claude Code .claude/skills/ — project-specific skills committed to the repository. Every team member gets the skills on clone with no extra setup, version-controlled alongside the code they document.
• Hermes ~/.hermes/skills/ — personal Hermes skills. Backed by a dotfiles repo for portability across machines.
• Hermes external_dirs — point Hermes at a shared team directory without copying skills locally. Add the path under skills.external_dirs in config.yaml. Skills update live when the directory changes, so team members get updates on the next session without any install step.

Don't dump everything in a flat directory. Group related skills by domain: deploy/, testing/, research/, writing/. Both platforms support nested skill directories, and grouping by purpose makes auditing faster as the library grows.

The Lifecycle in Practice

Moving a skill through defined stages deliberately prevents unnoticed debt accumulation. Each stage has a clear exit condition:

• Experiment (1-2 weeks) — write the skill and use it personally. Don't commit it to shared repos yet. If the skill doesn't survive a week of real use, it wasn't solving a real problem.
• Validate — run the test suite from Lesson 6. Confirm the skill fires on the right prompts and produces measurably better output. Check /skill-doctor (Claude Code) or Curator stats (Hermes) to verify invocation patterns match expectations.
• Stable — commit to version control. Add a version field, a CHANGELOG.md, and a named owner. Distribute to the team if relevant.
• Review — on the audit schedule below: is it still accurate? Still used? Still the best approach for the workflow it covers?
• Deprecate to Retire — follow the deprecation pattern from Lesson 8. Give users time to transition before removing the skill from the load directories.

Regular Audit Schedule

A library that grows without pruning becomes a token liability. Three audit intervals catch the most common problems before they affect real workflows:

• Monthly — run /skill-doctor (Claude Code) or check the Curator report (Hermes). Remove anything with zero invocations over the past month before the Level 0 cost accumulates further.
• Quarterly — re-run the test suite against all stable skills. Catch drift from tool updates before users encounter failures in production workflows.
• After major platform updates — check platform-specific field names against release notes. Model IDs, toolset names, and hook event names are the most likely to change between major versions of either platform.

Live Change Detection and the Reserved Name

Claude Code detects edits to skill files in ~/.claude/skills/, .claude/skills/, and any --add-dir directories within the current session — no restart needed. Edit a SKILL.md while Claude Code is running and the change takes effect on the next invocation of that skill.

Plugin files are the exception: changes to hooks/, .mcp.json, agents/, and output-styles/ inside a plugin directory require /reload-plugins. Live detection covers skill content; it does not cover plugin infrastructure.

One directory name is off-limits: never name a skill folder synced (in any capitalization). Claude Code reserves ~/.claude/skills/synced/ for skills downloaded from your claude.ai account. A folder named synced conflicts with cloud sync without raising an error that identifies the cause.