improve-skill

name	improve-skill
description	Use when running a maintenance cycle on a project skill or subagent — usage-log 레코드를 4분류로 진단해 스킬 md 개정안(diff)을 만들고 유저 승인 후 반영·소비 마킹한다. Triggers on "스킬 정비하자", "improve-skill 돌리자", pr 스킬 머지 단계의 임계 초과 제안을 유저가 수락했을 때. Does NOT trigger on 스킬 신규 작성(superpowers:writing-skills), 코드 리뷰 피드백 반영(feedback-reinforcement-learning), 유저가 지시한 일회성 스킬 문구 수정(직접 수정).

Improve Skill — 스킬 정비 사이클

usage-log에 쌓인 신호(발동·skill_end·correction)를 근거로 대상 스킬을 진단하고 개정한다. 반영은 유저 승인 후에만 — 하네스는 모든 후속 작업에 곱해지는 레버리지라 무감독 self-modify 금지.

1. 레코드 수집

대상 스킬의 미소비 레코드(마지막 improvement 마킹 이후)를 모은다:

python3 - << 'EOF'
import json, glob, os
NAME = "<대상 스킬>"
records = []
for p in sorted(glob.glob(os.path.expanduser("~/.claude/usage-log/*.jsonl"))):
    try:
        with open(p, encoding="utf-8") as f:
            for l in f:
                try:
                    records.append(json.loads(l))
                except ValueError:
                    continue
    except OSError:
        continue
mark = max((r.get("ts", "") for r in records
            if r.get("event") == "improvement" and r.get("name") == NAME), default="")
for r in records:
    if r.get("ts", "") <= mark:
        continue
    if r.get("name") == NAME or NAME in (r.get("skills") or []) or r.get("skills") == []:
        print(json.dumps(r, ensure_ascii=False))
EOF

• skills가 빈 correction(미귀속)도 함께 나온다 — 발동 실패 후보로 검토.
• 서브에이전트(code-analyzer 등)를 정비할 땐 event: agent 레코드(name 매칭)와 dispatch한 스킬(analyze·review)의 레코드를 함께 조회.
• 필요하면 prompt 이벤트를 훑어 "스킬이 발동됐어야 했는데 안 된" 지시를 찾는다.

2. 4분류 진단

수집한 레코드를 분류하고, finding마다 근거 레코드(ts)를 붙여 표로 정리한다:

분류	판정 신호	처방
발동 실패	스킬이 떠야 했던 prompt에 skill 이벤트 없음 / 미귀속 correction	description Triggers/Does NOT 경계 수정
준수 실패	skill_end partial 반복 — 특히 같은 clause	조항 강조·위치 재배치 (조항이 안 읽히는 문제)
설계 결함	compliance full인데 correction 발생	조항 내용 자체 개정
과잉 조항	같은 clause 이탈 반복 + correction 없음	조항 삭제·완화 (YAGNI)

3. 개정안

• 대상 스킬 md 원문을 읽고, 진단별 개정안을 diff 형태로 제시 — 무엇이 어떻게 바뀌고 왜(근거 레코드)인지.
• 스킬 작성 원칙은 superpowers:writing-skills를 따른다.

4. 승인·반영·마킹

• 유저가 승인한 항목만 반영. 프로젝트 스킬(.claude/skills/)은 커밋(개정 이력 = git), 글로벌(~/.claude/skills/)은 커밋 없이 수정.
• 반영 후 소비 마킹 — 같은 신호로 재발동되지 않게:

python3 .claude/hooks/log-record.py improvement --name <대상 스킬>