skill-management

name	skill-management
description	Create, update, test, and manage Agent Skills. Use when creating new skills, debugging existing ones, or organizing skill libraries. Based on official Claude Code documentation.
allowed-tools	Read, Glob, Grep, Edit, Write, Bash
license	MIT
metadata	{"author":"claude-docs","version":"1.0"}

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 분리)