aiskillstore/skill-management

Skill Management

스킬 생성, 업데이트, 테스트, 관리를 위한 공식 가이드입니다.

Skill 저장 위치

| 유형 | 경로 | 용도 | |------|------|------| | Personal | ~/.claude/skills/ | 개인 워크플로우, 실험적 스킬 | | Project | .claude/skills/ | 팀 워크플로우, Git 공유 | | Plugin | 플러그인 번들 | 외부 플러그인과 함께 배포 |

---

Skill 생성

1. 디렉토리 생성

# Personal Skill
mkdir -p ~/.claude/skills/my-skill-name

# Project Skill
mkdir -p .claude/skills/my-skill-name

2. SKILL.md 작성

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
allowed-tools: Read, Grep, Glob  # 선택사항
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

Frontmatter 규칙

| 필드 | 필수 | 규칙 | |------|------|------| | name | ✅ | 소문자, 숫자, 하이픈만 (최대 64자) | | description | ✅ | 수행 작업 + 사용 시기 (최대 1024자) | | allowed-tools | ❌ | 사용 가능 도구 제한 |

---

Skill 구조

단일 파일

my-skill/
└── SKILL.md

다중 파일

my-skill/
├── SKILL.md (필수)
├── references/
│   └── REFERENCE.md (선택)
├── scripts/
│   └── helper.py (선택)
└── templates/
    └── template.txt (선택)

참조 링크

상세 내용은 [references/REFERENCE.md](references/REFERENCE.md) 참조.

스크립트 실행:
```bash
python scripts/helper.py input.txt

---

## allowed-tools

도구 사용을 제한하여 안전한 스킬 생성:

```yaml
---
name: safe-file-reader
description: Read files without making changes.
allowed-tools: Read, Grep, Glob
---

사용 사례:

• 읽기 전용 스킬
• 보안에 민감한 워크플로우
• 기능 범위 제한

---

Skill 관리

목록 확인

# Personal Skills
ls ~/.claude/skills/

# Project Skills
ls .claude/skills/

# 특정 스킬 내용 확인
cat ~/.claude/skills/my-skill/SKILL.md

업데이트

# Personal Skill 편집
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill 편집
code .claude/skills/my-skill/SKILL.md

제거

# Personal
rm -rf ~/.claude/skills/my-skill

# Project
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"

---

팀 공유

1단계: 프로젝트에 추가

mkdir -p .claude/skills/my-skill
# SKILL.md 작성

2단계: Git 커밋

git add .claude/skills/
git commit -m "feat(skills): add my-skill"
git push

3단계: 팀 멤버 자동 적용

팀 멤버가 pull 시 자동으로 스킬 사용 가능.

---

모범 사례

1. 집중적 유지

✅ GOOD: "Git commit messages"
✅ GOOD: "PDF form filling"
❌ BAD: "Document processing" (분할 필요)

2. 명확한 description

# ✅ GOOD
description: Analyze Excel spreadsheets and create pivot tables. 
             Use when working with .xlsx files or tabular data.

# ❌ BAD
description: For files

3. 버전 문서화

## Version History
- v2.0.0 (2025-10-01): Breaking changes
- v1.0.0 (2025-09-01): Initial release

4. 권장 라인 수

| 대상 | 권장 | 최대 | |------|------|------| | SKILL.md | 200줄 | 500줄 | | REFERENCE.md | - | 제한 없음 |

---

문제 해결

Claude가 스킬을 사용하지 않음

1. description이 트리거 키워드 포함하는지 확인
2. 파일 경로 확인 (SKILL.md 대소문자)
3. YAML 구문 오류 확인

스킬 오류 발생

# YAML 구문 검증
cat SKILL.md | head -10

여러 스킬 충돌

• description으로 트리거 조건 명확화
• 스킬 범위 좁히기

---

예제

간단한 스킬

---
name: commit-helper
description: Generates clear commit messages from git diffs.
---

# Commit Helper

1. Run `git diff --staged` to see changes
2. Suggest commit message with:
   - Summary under 50 characters
   - Detailed description

읽기 전용 스킬

---
name: code-reviewer
description: Review code for best practices.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist
1. Code organization
2. Error handling
3. Security concerns

---

Checklist

스킬 생성 시:

• [ ] name: 소문자+숫자+하이픈, 64자 이내
• [ ] description: 작업 내용 + 사용 시기
• [ ] 단일 책임 원칙 (한 가지 역할)
• [ ] 예시 포함
• [ ] 500줄 이내 (초과 시 REFERENCE 분리)