skill-curator — the librarian for your Agent Skills

The problem문제

Skills accumulate. Nobody curates them.스킬은 쌓이기만 하고, 아무도 정리하지 않습니다.

Copies drift across harness roots and project checkouts until nobody can say which package actually wins. The usual fix — telling an agent to "clean up my skills" — is exactly the wrong tool for the job.

복사본이 하니스 루트와 프로젝트 체크아웃 곳곳으로 흩어지다 보면, 결국 어떤 패키지가 실제로 우선하는지 아무도 말할 수 없게 됩니다. 그렇다고 에이전트에게 "내 스킬 좀 정리해줘"라고 맡기는 건, 이 일에 정확히 맞지 않는 도구입니다.

An agent guessing짐작하는 에이전트

Invents usage counts it cannot observe. Deletes a skill you wrote last week because it "looks unused." Merges two packages and silently drops the resources one of them depended on. No undo.

관측할 수도 없는 사용 횟수를 지어냅니다. 지난주에 직접 만든 스킬을 "안 쓰는 것 같다"며 지웁니다. 두 패키지를 병합하면서 한쪽이 의존하던 리소스를 조용히 흘립니다. 되돌리기는 없습니다.

An engine reporting보고하는 엔진

Hashes complete packages, resolves precedence, flags collisions, and refuses to prune anything you never adopted. The model only judges semantic overlap — the part that actually needs judgment.

전체 패키지를 해시하고, 우선순위를 해석하고, 충돌을 표시하며, adopt하지 않은 것은 절대 프루닝하지 않습니다. 모델은 의미적 중복 — 실제로 판단이 필요한 부분 — 만 판정합니다.

What it does하는 일

Facts from the engine, judgment from the model.사실은 엔진에서, 판단은 모델에서.

The split is deliberate, and it is the whole design.이 분리는 의도된 것이고, 설계의 전부입니다.

Cross-harness discovery하니스 횡단 탐색

Scans user and project roots for Claude Code, Codex, Cursor, Gemini CLI, and OpenCode. Add anything else with --root or config.json.

Claude Code, Codex, Cursor, Gemini CLI, OpenCode의 사용자·프로젝트 루트를 스캔합니다. 그 외 루트는 --root나 config.json으로 추가하세요.

Validation with real states실제 상태로 분류하는 검증

Every discovered SKILL.md lands in exactly one state: active, stale, unmanaged, pinned, protected, invalid, or archived.

발견된 모든 SKILL.md는 정확히 하나의 상태를 갖습니다: active, stale, unmanaged, pinned, protected, invalid, archived.

Duplicates, not lookalikes비슷한 게 아니라 진짜 중복

Exact duplicates by complete-package hash. Name collisions with precedence. Semantic overlap left to the model, with evidence attached.

전체 패키지 해시로 정확한 중복을 판정합니다. 이름 충돌은 우선순위와 함께 보고합니다. 의미적 중복은 근거를 붙여 모델에 넘깁니다.

Opt-in lifecycle옵트인 라이프사이클

A newly discovered skill is unmanaged. It cannot enter age-based pruning until you adopt it. Age alone is never evidence.

새로 발견된 스킬은 unmanaged입니다. adopt하기 전에는 나이 기반 프루닝에 들어가지 않습니다. 오래됐다는 것만으로는 근거가 되지 않습니다.

Pins and protection핀과 보호

pin blocks archive outright. Git-tracked project skills get soft protection so a repo's own skills are not shelved behind your back.

pin은 아카이브를 원천 차단합니다. Git으로 추적되는 프로젝트 스킬은 소프트 보호를 받아, 저장소 소유의 스킬이 모르는 사이 치워지지 않습니다.

Archive, never delete삭제 대신 아카이브

Archiving moves the whole package plus a manifest. list-archived and restore bring it back, never overwriting an occupied path.

아카이브는 전체 패키지와 매니페스트를 함께 옮깁니다. list-archived와 restore로 되돌리며, 이미 점유된 경로는 덮어쓰지 않습니다.

Snapshots and rollback스냅샷과 롤백

Snapshot before risky consolidation. rollback preserves any changed occupant under the snapshot's conflicts/ directory.

위험한 통합 작업 전에 스냅샷을 찍으세요. rollback은 변경된 점유자를 스냅샷의 conflicts/ 아래에 보존합니다.

Symlink-aware심볼릭 링크 인식

One canonical copy linked into many roots is a normal setup. Archiving a symlinked entry moves the link and leaves the target untouched.

하나의 정본을 여러 루트에 링크해 두는 건 흔한 구성입니다. 링크된 항목을 아카이브하면 링크만 옮기고 대상은 그대로 둡니다.

Explicit invocation only명시적 호출만

disable-model-invocation: true. The skill never fires on a hunch — it runs when you ask, and only does what your request authorized.

disable-model-invocation: true. 짐작만으로 실행되지 않습니다. 요청했을 때만 동작하고, 요청이 허가한 일만 합니다.

Install설치

Pick your harness.쓰는 하니스를 고르세요.

Python 3.9+ and local filesystem access. Nothing else.Python 3.9+와 로컬 파일시스템 접근. 그 외에는 필요 없습니다.

Claude Code Codex Gemini CLI Cursor / OpenCode / Amp Script & manual스크립트 & 수동

$ claude plugin marketplace add cskwork/skill-curator
$ claude plugin install skill-curator@skill-curator

Then type /skill-curator. Verify with claude plugin list.

그다음 /skill-curator를 입력하세요. claude plugin list로 확인합니다.

$ codex plugin marketplace add cskwork/skill-curator --ref main
$ codex plugin add skill-curator@skill-curator

Then type $skill-curator. Verify with codex plugin list.

그다음 $skill-curator를 입력하세요. codex plugin list로 확인합니다.

$ gemini extensions install https://github.com/cskwork/skill-curator

Verify with gemini extensions list.

gemini extensions list로 확인합니다.

$ npx skills add cskwork/skill-curator       # project scope
$ npx skills add cskwork/skill-curator -g    # global scope

$ npx skills add cskwork/skill-curator       # 프로젝트 범위
$ npx skills add cskwork/skill-curator -g    # 전역 범위

Then type /skill-curator in a new agent chat.

새 에이전트 대화에서 /skill-curator를 입력하세요.

$ curl -fsSL https://raw.githubusercontent.com/cskwork/skill-curator/main/install.sh | bash

# or, from a clone, with more control
$ ./install.sh --list       # show detected skills roots
$ ./install.sh --dry-run    # show what would be written
$ ./install.sh --all        # install into every detected root
$ ./install.sh --uninstall  # remove installed copies

$ curl -fsSL https://raw.githubusercontent.com/cskwork/skill-curator/main/install.sh | bash

# 또는 클론한 뒤 더 세밀하게
$ ./install.sh --list       # 감지된 skills 루트 표시
$ ./install.sh --dry-run    # 무엇이 쓰일지만 표시
$ ./install.sh --all        # 감지된 모든 루트에 설치
$ ./install.sh --uninstall  # 설치된 복사본 제거

The installer backs up any existing package before replacing it. Full matrix in INSTALL.md.

설치 스크립트는 기존 패키지를 교체하기 전에 백업합니다. 전체 표는 INSTALL.md에 있습니다.

First run첫 실행

Ask for a report before you ask for a change.변경을 요청하기 전에, 먼저 리포트를 요청하세요.

The skill is built to be boring on the first pass: look, then decide, then act, then verify.이 스킬은 첫 패스에서 일부러 지루하게 설계됐습니다. 보고, 정하고, 실행하고, 검증합니다.

Review검토 Ask your agent: “Use skill-curator to review all installed coding-agent skills. Show invalid packages, name collisions, exact duplicates, protected skills, and a dry-run archive plan. Do not mutate anything.” 에이전트에게 이렇게 요청하세요: “Use skill-curator to review all installed coding-agent skills. Show invalid packages, name collisions, exact duplicates, protected skills, and a dry-run archive plan. Do not mutate anything.”
Decide판단 Each recommendation names IDs, paths, evidence, protection status, and the rollback route. Keep, pin, patch, archive, or consolidate — smallest reversible action wins. 모든 권고에는 ID, 경로, 근거, 보호 상태, 되돌리기 경로가 명시됩니다. 유지·핀·수정·아카이브·통합 중 가장 작고 되돌릴 수 있는 조치를 고르세요.
Apply적용 Nothing moves without --apply, and only for the branch your request authorized. Ambiguous names are refused; the displayed ID or exact path is required. --apply 없이는 아무것도 움직이지 않고, 요청이 허가한 분기에 대해서만 적용됩니다. 모호한 이름은 거부되며, 표시된 ID나 정확한 경로가 필요합니다.
Verify검증 Re-run review and validate, confirm manifests and hashes exist, confirm unselected packages are untouched — and read back the undo command. review와 validate를 다시 실행해 매니페스트와 해시가 있는지, 선택하지 않은 패키지가 그대로인지 확인하고, 되돌리기 명령을 읽어보세요.

Reference레퍼런스

The engine.엔진.

One file, no dependencies: skills/skill-curator/scripts/curator.py.파일 하나, 의존성 없음: skills/skill-curator/scripts/curator.py.

Command커맨드	Purpose역할
`review`	Full inventory with per-skill state and recommendations스킬별 상태와 권고를 담은 전체 인벤토리
`status`	Compact summary of the current library현재 라이브러리의 요약
`scan`	Raw discovery across all configured roots설정된 모든 루트에 대한 원시 탐색
`validate`	Frontmatter and package structure checks프론트매터와 패키지 구조 검사
`duplicates`	Exact duplicates, name collisions, precedence정확한 중복, 이름 충돌, 우선순위
`pin` · `unpin`	Protect a skill from archive and prune아카이브·프루닝으로부터 스킬 보호
`adopt`	Opt a skill into age-based lifecycle management나이 기반 라이프사이클 관리 대상으로 편입
`mark-used`	Record explicit usage evidence명시적 사용 증거 기록
`archive`	Move a complete package into the archive (dry run by default)전체 패키지를 아카이브로 이동 (기본 드라이런)
`prune`	Archive every eligible adopted skill (dry run by default)조건을 만족하는 adopted 스킬 일괄 아카이브 (기본 드라이런)
`list-archived`	List recoverable archived packages복원 가능한 아카이브 목록
`restore`	Return an archived package to its original path아카이브된 패키지를 원래 경로로 복원
`snapshot`	Copy packages before risky edits위험한 편집 전에 패키지 복사
`rollback`	Restore a snapshot, preserving any changed occupant스냅샷 복원, 변경된 점유자는 보존

State lives in one place.상태는 한곳에 모입니다.

Defaults to ~/.skill-curator/. Relocate it with SKILL_CURATOR_HOME.기본 위치는 ~/.skill-curator/이며, SKILL_CURATOR_HOME으로 옮길 수 있습니다.

state.json                 registry and lifecycle evidence
config.json                optional custom roots and thresholds
archive/<archive-id>/      complete moved packages and manifests
backups/<snapshot-id>/     complete copied snapshots and conflicts
reports/                   optional command reports

state.json                 레지스트리와 라이프사이클 증거
config.json                커스텀 루트와 임계값 (선택)
archive/<archive-id>/      이동된 전체 패키지와 매니페스트
backups/<snapshot-id>/     복사된 전체 스냅샷과 충돌본
reports/                   커맨드 리포트 (선택)

Honest limits솔직한 한계

What it will not pretend to do.할 수 있는 척하지 않는 것들.

It is an on-demand skill, not a background daemon. Coding harnesses do not expose one portable invocation-telemetry API, so the curator does not invent usage counts. It records explicit mark-used, first observation, observed content changes, and restores. Harness-specific hooks can call mark-used later without changing the archive model.

온디맨드 스킬이지 백그라운드 데몬이 아닙니다. 코딩 하니스들은 이식 가능한 단일 호출 텔레메트리 API를 제공하지 않으므로, 큐레이터는 사용 횟수를 지어내지 않습니다. 기록하는 것은 명시적인 mark-used, 최초 관측, 관측된 내용 변경, 복원뿐입니다. 하니스별 훅이 나중에 mark-used를 호출해도 아카이브 모델은 바뀌지 않습니다.

Age is not evidence. A skill you wrote and never ran is still a skill you wrote. Nothing you have not explicitly adopted can enter age-based pruning, and nothing is deleted — only archived, with a restore path.

오래됐다는 건 근거가 아닙니다. 만들어 놓고 한 번도 안 돌린 스킬도 여전히 당신이 만든 스킬입니다. 명시적으로 adopt하지 않은 것은 나이 기반 프루닝에 들어가지 않으며, 삭제되지 않고 복원 경로가 있는 아카이브로만 이동합니다.