---

name: skill-manager description: 스킬 생태계를 관리하고 품질을 유지합니다. 전체 스킬 현황 파악, 품질 분석, 문제점 진단, 개선 제안, 자동 수정, 새 스킬 생성 가이드를 제공합니다. "스킬 분석", "스킬 현황", "스킬 만들기", "스킬 개선" 요청 시 활성화됩니다.

Skill Manager - 스킬 관리 및 품질 유지

Overview

agent-skills 저장소의 모든 스킬을 관리하고 품질을 유지하는 메타 스킬입니다.

핵심 기능:

• 인벤토리: 전체 스킬 목록 및 메타데이터 파악
• 품질 분석: 문서 완성도, 구조 일관성 점수화
• 토큰 효율성 분석: 스크립트 활용, 도구 호출 최소화 검토
• 문제 진단: 중복, 불일치, 미완성 항목 발견
• 개선 가이드: 구체적 개선 방향 및 우선순위 제시
• 자동 수정: 필요시 스킬 문서 직접 수정
• 템플릿 제공: 새 스킬 생성을 위한 표준 템플릿

When to Use

이 스킬은 다음 상황에서 활성화됩니다:

명시적 요청:

• "스킬 현황 분석해줘"
• "스킬 품질 점검해줘"
• "새 스킬 만들어줘"
• "스킬 개선해줘"
• "스킬 목록 보여줘"
• "토큰 효율성 검토해줘"
• "스킬 최적화해줘"

자동 활성화:

• 새 스킬 생성 요청 시
• 기존 스킬 수정 요청 시
• 스킬 구조에 대한 질문 시

Workflow

Mode 1: 스킬 인벤토리 (현황 파악)

Step 1: 스킬 디렉토리 스캔

Copy# 모든 SKILL.md 파일 탐색
find /path/to/agent-skills -name "SKILL.md" -type f

Step 2: 메타데이터 추출 각 SKILL.md에서 다음을 추출:

• YAML frontmatter (name, description)
• 카테고리 (디렉토리 기준)
• 라인 수
• 섹션 구성

Step 3: 인벤토리 테이블 생성

Copy| 스킬 | 카테고리 | 라인 | 스크립트 | 완성도 |
|------|----------|------|----------|--------|
| skill-name | category | 123 | ✅/❌ | 85% |

---

Mode 2: 품질 분석

Step 1: 필수 섹션 체크

Step 2: 품질 점수 계산

Copy완성도 = Σ(섹션 존재 × 가중치) + 구조 보너스
구조 보너스 = 일관된 포맷(+5%) + 코드 예시(+5%) + 테이블 사용(+5%)

Step 3: 등급 부여

---

Mode 3: 문제 진단

다음 문제 유형을 탐지합니다:

구조적 문제:

• 필수 섹션 누락
• YAML frontmatter 누락/불완전
• 비표준 섹션 구조

내용 문제:

• 설명 없는 코드 블록
• 예시 없는 기능 설명
• 모호한 활성화 조건

경로 문제 (Critical):

• 외부 스크립트 참조 금지 (예: ~/scripts/, ~/callabo-base/run.sh)
• 스킬 내장 스크립트는 반드시 상대 경로 사용: ./scripts/
• 절대 경로 금지 (예: /home/username/..., ~/.claude/skills/<skill-name>/scripts/)
• 허용 경로: ~/.claude/, ~/.agents/, ~/work/ (사용자 워크스페이스)

경로 검사 방법:

Copy# 외부 스크립트 참조 탐지
grep -r "~/scripts/" */SKILL.md
grep -r "~/callabo-base/" */SKILL.md

# 절대 스킬 경로 탐지 (상대 경로로 변경 필요)
grep -r "~/.claude/skills/.*/scripts/" */SKILL.md

생태계 문제:

• 스킬 간 기능 중복
• 순환 의존성
• 고아 스킬 (참조되지 않음)

진단 결과 형식:

Copy## 문제 진단 결과

### 🔴 Critical (즉시 수정)
- [스킬명] 문제 설명

### 🟡 Warning (개선 권장)
- [스킬명] 문제 설명

### 🔵 Info (참고)
- [스킬명] 정보

---

Mode 4: 개선 가이드

문제별 구체적 해결 방안 제시:

섹션 누락 시:

Copy### [스킬명] 개선 필요

**누락 섹션:** Examples

**권장 추가 내용:**
예시 1: 기본 사용법
예시 2: 고급 사용법

**템플릿:**
## Examples

### 예시 1: [상황 설명]
\`\`\`
[사용자 요청]
→ [Claude 응답/동작]
\`\`\`

---

Mode 5: 자동 수정

사용자 확인 후 직접 스킬 문서를 수정합니다.

자동 수정 가능 항목:

• 누락된 필수 섹션 추가 (빈 템플릿)
• YAML frontmatter 보완
• 일관된 포맷으로 변환
• 오타/형식 오류 수정
• 경로 수정: ~/.claude/skills/*/scripts/ → ./scripts/
• 외부 스크립트 복사 및 경로 변경

경로 자동 수정 예시:

Copy# Before (절대 경로)
~/.claude/skills/callabo-tmux/scripts/run.sh

# After (상대 경로)
./scripts/run.sh

자동 수정 불가 항목:

• 실제 내용 작성 (사용자 입력 필요)
• 기능 변경이 필요한 수정
• 의미적 판단이 필요한 항목

수정 절차:

1. 문제 목록 제시
2. 수정 계획 설명
3. 사용자 승인 요청
4. Edit 도구로 수정 수행
5. 수정 결과 보고

---

Mode 6: 새 스킬 생성

Step 1: 정보 수집

AskUserQuestion으로 다음을 확인:

• 스킬 이름
• 목적/설명
• 카테고리
• 주요 기능
• 활성화 조건

Step 2: 템플릿 적용

references/SKILL_TEMPLATE.md 템플릿을 기반으로 초안 생성

Step 3: 초안 검토

생성된 초안을 사용자에게 보여주고 피드백 수집

Step 4: 파일 생성

승인 후 해당 카테고리에 스킬 디렉토리 및 SKILL.md 생성

---

Mode 7: 토큰 효율성 분석

스킬이 Claude의 컨텍스트 토큰을 효율적으로 사용하는지 검토합니다.

Step 1: 토큰 효율성 체크리스트

Step 2: 효율성 등급 부여

Step 3: 토큰 절약 분석

Copy## 토큰 효율성 분석: [스킬명]

### 현재 상태
- 스크립트: ✅/❌
- 예상 도구 호출: N회

### 최적화 시
- 예상 도구 호출: M회
- 절약률: X%

### 권장 사항
1. [구체적 개선 방안]

효율성 판단 기준:

Copy스크립트 없이 수동으로 처리하는 경우:
┌─────────────────────────────────────────┐
│ git status          → 1회             │
│ git branch          → 1회             │
│ git log             → 1회             │
│ git diff            → 1회             │
│ 데이터 파싱         → 컨텍스트 소비    │
│ 총: 4+ 도구 호출 + 파싱 오버헤드       │
└─────────────────────────────────────────┘

스크립트로 통합한 경우:
┌─────────────────────────────────────────┐
│ script.sh collect   → 1회             │
│ 구조화된 출력       → 즉시 사용 가능   │
│ 총: 1회 도구 호출                      │
└─────────────────────────────────────────┘

토큰 절약률 = (기존 호출 - 최적화 호출) / 기존 호출 × 100

스크립트 권장 기준:

스크립트화 불가 (예외):

예: proposal-analyzer (제안서 분석), code-reviewer (코드 리뷰) 등

---

스킬 표준 구조

디렉토리 구조

Copycategory/
└── skill-name/
    ├── SKILL.md           # 필수: 스킬 정의
    ├── scripts/           # 선택: 자동화 스크립트
    │   └── main.py
    ├── config/            # 선택: 설정 파일
    │   └── settings.yaml
    ├── templates/         # 선택: 템플릿 파일
    └── references/        # 선택: 참고 문서

경로 규칙 (중요)

스킬은 ./install.sh로 ~/.claude/skills/에 설치된 후 사용됩니다.

허용되는 경로:

금지되는 경로:

경로 검증 방법:

Copy# 절대 경로 검사 (금지 패턴)
grep -rn "/home/" --include="*.md" | grep -v "~/.claude" | grep -v "~/.agents"

# /home/user는 예시로 허용, /home/<실제사용자명>은 금지

스크립트 경로 표준:

Copy## Script Location

\`\`\`
SCRIPT: ~/.claude/skills/<skill-name>/scripts/<script>.sh
\`\`\`

SKILL.md 표준 형식

Copy---
name: skill-name
description: 한 줄 설명 (활성화 키워드 포함)
---

# Skill Title

## Overview
[필수] 스킬의 목적과 핵심 기능 설명

## When to Use
[필수] 명시적/자동 활성화 조건

## Prerequisites
[선택] 사전 요구사항 (환경변수, 의존성 등)

## Workflow
[필수] 단계별 실행 절차

## Examples
[필수] 최소 2개 이상의 사용 예시

## Configuration
[선택] 설정 옵션

## Best Practices
[필수] DO / DON'T 목록

## Troubleshooting
[선택] 일반적인 문제와 해결책

## Resources
[선택] 스크립트, 참고 문서 목록

---

Examples

예시 1: 전체 스킬 현황 분석

Copy사용자: 스킬 현황 분석해줘

Claude: (skill-manager 활성화)
agent-skills 저장소를 스캔합니다...

## 스킬 인벤토리

| 스킬 | 카테고리 | 완성도 | 등급 |
|------|----------|--------|------|
| multi-llm-agent | agents | 95% | A |
| planning-agents | agents | 92% | A |
| git-commit-pr | development | 78% | B |
| proposal-analyzer | business | 52% | D |
...

## 요약
- 총 스킬: 7개
- 평균 완성도: 75%
- 개선 필요: 2개 (proposal-analyzer, git-commit-pr)

예시 2: 특정 스킬 개선

Copy사용자: proposal-analyzer 스킬 개선해줘

Claude: proposal-analyzer 스킬을 분석합니다...

## 문제 진단

🔴 Critical:
- Overview 섹션 누락
- When to Use 섹션 누락
- Best Practices 섹션 누락

🟡 Warning:
- YAML frontmatter에 trigger_keywords 없음

## 개선 계획

1. Overview 섹션 추가
2. When to Use 섹션 추가
3. Best Practices 섹션 추가

진행할까요? [Y/n]

예시 3: 새 스킬 생성

Copy사용자: code-review 스킬 만들어줘

Claude: 새 스킬을 생성하기 위해 몇 가지 질문드립니다.

[질문 1] 이 스킬의 주요 목적은?
[질문 2] 어떤 카테고리에 배치할까요?
[질문 3] 활성화 키워드는?

(답변 수집 후)

## 생성될 스킬 미리보기

---
name: code-review
description: 코드 리뷰 가이드라인 및 체크리스트 제공...
---

# Code Review

## Overview
...

이대로 생성할까요?

예시 4: 토큰 효율성 분석

Copy사용자: 스킬 토큰 효율성 검토해줘

Claude: 전체 스킬의 토큰 효율성을 분석합니다...

## 토큰 효율성 분석 결과

| 스킬 | 스크립트 | 예상 호출 | 효율성 | 등급 |
|------|:--------:|:---------:|:------:|:----:|
| context-worktree | ✅ | 1~2회 | 85% | ⚡ |
| git-commit-pr | ❌ | 5~6회 | 40% | ⚠️ |
| multi-llm-agent | ✅ | 2회 | 75% | ✅ |
| proposal-analyzer | ❌ | 4회 | 45% | ⚠️ |

## 개선 권장

### 🔴 즉시 개선 필요
- **git-commit-pr**: 보안 검증 + 변경사항 수집을 스크립트로 통합 권장
  - 현재: git status, git diff, grep 패턴 검사 등 5~6회 호출
  - 개선: `git-commit-check.sh` 스크립트로 1회 호출

### 🟡 개선 권장
- **proposal-analyzer**: 문서 분석 전처리 스크립트 추가 권장

## 요약
- 평균 효율성: 61%
- 최적화 필요: 2개 스킬
- 예상 토큰 절약: 약 40%

---

Best Practices

DO:

• 정기적으로 스킬 현황 점검 (새 스킬 추가 후)
• 문제 발견 시 즉시 개선
• 표준 템플릿 준수
• 스킬 간 의존성 명시
• 변경 시 관련 스킬 영향도 확인
• 3회 이상 반복되는 도구 호출은 스크립트로 통합
• 스크립트 출력은 마크다운 테이블/구조화된 형식 사용
• 스킬 내장 스크립트는 ./scripts/ 상대 경로 사용
• 외부 스크립트 의존 시 스킬 내부로 복사

DON'T:

• 표준 구조 무시하고 스킬 생성
• 중복 기능의 스킬 생성
• 불완전한 상태로 스킬 배포
• 의존성 없이 다른 스킬 참조
• 테스트 없이 자동 수정 적용
• 여러 git/시스템 명령을 개별 호출로 나열
• 파싱이 어려운 자유 형식 출력 사용
• 외부 경로 참조 (예: ~/scripts/, ~/callabo-base/)
• 절대 스킬 경로 사용 (예: ~/.claude/skills/*/scripts/)

---

스킬 카테고리 가이드

---

Integration

이 스킬은 다른 모든 스킬과 상호작용합니다:

• 분석 대상: 모든 스킬
• 의존: static-index (WHOAMI.md 참조 시)
• 영향: 모든 스킬의 품질과 일관성

---

Troubleshooting

스킬 스캔 실패

Copy# 디렉토리 권한 확인
ls -la /path/to/agent-skills

# SKILL.md 파일 존재 확인
find . -name "SKILL.md"

품질 점수 이상

• 섹션 제목이 정확히 일치하는지 확인 (대소문자 구분)
• YAML frontmatter 형식 확인

자동 수정 실패

• 파일 쓰기 권한 확인
• 수정 전 백업 권장 (git commit)