self-improving-skills

Claude Self-Improving Skills

English | 한국어

Hermes Agent-style self-improvement for Claude Code.

It turns hard-won workflow lessons into reusable SKILL.md files, validates skill edits, curates stale knowledge, and (since v0.9.0) lets a team share learned skills through a git repo — without ever overwriting anyone's personal customizations.

Claude Code already has hooks, subagents, slash commands, and skills. This plugin wires those primitives into a closed learning loop inspired by Nous Research Hermes Agent:

complex task → distill what worked → save/patch a skill → rediscover next session

Why this exists

Most coding agents can solve a hard problem once. Fewer can reliably remember the reusable part of that work and apply it later.

Hermes Agent has first-class procedural memory through skills and a curator loop. This project ports that idea into Claude Code as a plugin:

• Detect complex work using transcript/tool-call signals.
• Nudge the agent at the right time to distill the reusable technique.
• Write or patch ~/.claude/skills/<name>/SKILL.md through a dedicated subagent.
• Validate and roll back malformed skill edits automatically.
• Track usage so stale generated skills can be archived instead of piling up forever.
• Share proven skills with your team — opt-in, review-gated, personalization always wins.

Features

• Automatic distillation nudge: a Stop hook blocks once per segment of work when enough tool calls and file edits accumulated since the last distillation. A declined nudge stays declined; it only re-fires after another threshold of new work. The nudge includes the transcript path so the background distiller can read what actually happened.
• Dedicated distiller subagent: prefers patching existing skills, then umbrella skills, then adding reference files, and creates a new class-level skill only as a last resort. Skill descriptions follow Anthropic's skill-creator guidance (third-person situation match with concrete trigger phrases).
• Skill edit safety: pre-edit backups, post-edit validation, provenance stamping, and automatic rollback on malformed SKILL.md. Non-blocking quality advisories (e.g. over-long descriptions that cost context in every session).
• Accurate usage telemetry: skill use/view/patch counts in ~/.claude/self-improve/skill_usage.json. Patch counting runs in the PostToolUse hook so edits made by background subagents are captured too, and bulk reads during curation never reset a skill's idle clock.
• Curator loop: unused agent-created skills go stale after 30 days and are archived (recoverably) after 90. Skills proven by repeated use (use_count >= 3) age at half speed. The LLM curation pass (/curate-skills) is an umbrella-building consolidation modeled on Hermes' curator prompt — plan first, apply only after approval.
• Team skill sharing (v0.9.0): share learned skills through a team git repo with origin-hash sync — see below.
• Manual commands: /distill-skill, /curate-skills, /curator-status, /prune-skills, /archive-skill, /pin-skill, /restore-skill, /share-skill, /sync-team-skills, /propose-plugin-improvement.
• Fail-safe hooks: hook errors approve the original action instead of breaking your Claude Code session.

Team skill sharing

Point the plugin at your team's (usually private) skills repo — nothing is hardcoded:

// ~/.claude/self-improve/team_config.json
{
  "repo": "your-org/your-team-skills",
  "subdir": "skills"
}

• Publish with /share-skill <name>: the skill is scanned (secrets, local paths, injection patterns), generalized (techniques stay, personal style is stripped), shown to you as a diff, and opened as a PR against the team repo. A human merges.
• Receive with /sync-team-skills: a fresh shallow clone, a read-only plan you confirm, then per-skill transactional apply.

The origin-hash rule makes sharing safe by construction. Each installed team skill records a deterministic content hash at install time:

Your local copy	Sync behavior
Untouched (hash == origin)	Auto-updated to the team's latest
Customized by you	Never overwritten — a one-time "diverged" notice; share your version back if you want
Deleted or archived by you	Never re-installed (until --reinstall <name>)
Name collides with a personal skill	Skipped with a warning

Skills are instructions to an agent — i.e. a prompt-injection vector — so every write of team content (first install and later updates) passes a static scanner (secrets, destructive commands, injection markers, symlinks, hidden files, size caps). Blocked content lands in quarantine, never in ~/.claude/skills. Team skills are marked created_by: team and are never touched by your personal curator: their owner is the team repo.

Install