skills-hub

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:
```json
{
  "<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 foo@1.2.0` (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)

```yaml
---
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.

From kjuhwa/skills-hub, MIT.

More from kjuhwa/skills-hub