Skills hub

Skills Hub

Central orchestration layer for the kjuhwa/skills knowledge repository.

Remote Repository

• URL: https://github.com/kjuhwa/skills.git
• Clone cache: ~/.claude/skills-hub/remote/ (shallow, auto-refreshed)
• Registry: ~/.claude/skills-hub/registry.json — tracks installed skills, source path, version, install date

Remote Layout (category-separated)

skills/
  <category>/           # apm, backend, frontend, devops, testing, db, security, ai, ...
    <skill-name>/
      SKILL.md          # frontmatter: name, description, tags, triggers, category, version
      content.md        # prompt / knowledge body
      examples/         # optional
  index.json            # flat catalog built from SKILL.md frontmatter
  CATEGORIES.md         # human-readable category list
  README.md

Local Install Destinations

• Project-scoped: .claude/skills/<skill-name>/ (default when inside a project with .claude/)
• User-scoped: ~/.claude/skills/<skill-name>/ (fallback, or --global flag)

Registry entry format:

{
  "<skill-name>": {
    "category": "apm",
    "source_commit": "a1b2c3",
    "installed_at": "2026-04-14T10:00:00Z",
    "synced_at": "2026-04-15T09:30:00Z",
    "scope": "project|global",
    "version": "1.0.0",
    "pinned": false
  }
}

Versioning Contract (git tags)

• Every published skill version gets an annotated tag: skills/<name>/v<semver> (e.g. skills/foo/v1.2.0).
• /skills_publish creates and pushes the tag as part of the publish flow; bumps the version in SKILL.md frontmatter if the existing tag is unchanged.
• /init_skills [email protected] (or --version=1.2.0) installs the files at that tag and sets pinned: true in the registry.
• /skills_sync --skill=foo --version=1.1.0 performs a rollback to that tag (also pins).
• /skills_sync --skill=foo --unpin clears the pin so the skill tracks latest again.
• Bulk /skills_sync skips pinned skills unless --force.

Command Map

Slash Command	Purpose
/init_skills <keyword>	Search remote by keyword/category → interactive install
/skills_search <keyword>	Preview-only remote search
/skills_list	Show installed skills (local + scope + source)
/skills_sync	Refresh remote cache + update installed skills
/skills_extract	Full project scan → generate skill drafts in .skills-draft/
/skills_extract_session	Current session only → drafts from recent changes
/skills_publish	Review drafts → push to remote as branch + optional PR
/skills_merge <selectors...>	Combine 2+ remote skills/knowledge into one new draft (read-only on remote)
/skills_split <selector>	Decompose one remote skill/knowledge into N smaller drafts (read-only on remote)
/skills_refactor	Scan remote for merge + split candidates and produce both kinds of drafts in one pass
/skills_finalize	End-of-project: extract → review → publish → cleanup drafts
/skills_cleanup	Remote maintenance: dedupe, re-index, stale removal (dry-run default)
/skills_remove <name>	Uninstall local skill
/skills_bootstrap_update [--version=x.y.z]	Update slash-command files themselves to latest or a tagged version
/skills_bootstrap_publish [--bump=…]	Publish local command edits to remote with a bootstrap/v<ver> tag

Safety Rules

1. Never push directly to main — always a branch skills/<category>/<name>-<date>.
2. publish and cleanup run dry-run first, require explicit user approval before git write operations.
3. extract writes to .skills-draft/ (gitignored by default), never directly to remote.
4. Skill names must match [a-z0-9-]+; categories from CATEGORIES.md (new ones require explicit approval).
5. Before installing, check registry for name collision; prompt on conflict.

Extract Heuristics

Only keep patterns that are generalizable. Drop project-specific code.

Signals that promote a pattern to a skill draft:

• Appears across multiple files with small variations
• Solves a recurring problem documented in commit messages
• User explicitly corrects behavior (see feedback memory)
• New tool/library integration with non-trivial setup
• Debugging workflow that succeeded after iteration

Signals that demote (skip):

• Contains business names, credentials, internal URLs
• Tied to one-off migration or hotfix
• Reproduces framework defaults

Metadata Contract (SKILL.md frontmatter)

---
name: <kebab-case-name>
description: <one sentence, specific, trigger-friendly>
category: <from CATEGORIES.md>
tags: [list, of, keywords]
triggers: [keyword patterns for auto-activation]
source_project: <originating project name or "manual">
version: 1.0.0
---

Integration Notes

• Works alongside OMC skills — installed skills appear under ~/.claude/skills/ or .claude/skills/ and are auto-discovered by Claude Code's skill loader.
• Respects DISABLE_OMC and OMC_SKIP_HOOKS.
• All git operations use git -C ~/.claude/skills-hub/remote — never touch the user's project git state.