skills-ref

name	skills-ref
description	스킬 디렉토리를 스캔하여 CLAUDE.md에 Available Skills 섹션을 XML 구조로 생성합니다. 스킬 등록, 스킬 목록 생성, CLAUDE.md 스킬 섹션, skills ref, 스킬 인덱스, available skills 작성 요청 시 활성화.

Skills Ref

스킬 디렉토리를 스캔하여 CLAUDE.md에 <available-skills> XML 섹션을 생성합니다.

CRITICAL: 사용자 입력 먼저

이 스킬은 어떤 분석이나 명령 실행보다 먼저, 반드시 사용자에게 아래 두 가지를 질문해야 합니다. 사용자 응답 없이 절대 진행하지 마세요.

1. 스캔할 스킬 디렉토리는 어디인가요? (예: .claude/skills, skills, 기타 경로)
2. CLAUDE.md 파일 경로는? (예: CLAUDE.md, .claude/CLAUDE.md, 기타)

• skills/ 같은 기본값을 가정하지 마세요. 반드시 사용자에게 물어보세요.
• 레포마다 스킬 디렉토리가 다릅니다:
  • 일반 프로젝트 → .claude/skills/
  • 스킬 라이브러리 레포 → skills/ (배포용), .claude/skills/ (프로젝트 자체용)
  • 모노레포 → packages/{pkg}/.claude/skills/

사용자가 디렉토리를 알려준 후에만 아래 워크플로우를 진행합니다.

---

워크플로우

Step 1: uvx 실행 환경 확인

uvx로 skills-ref를 실행할 수 있는지 확인합니다:

uvx --from skills-ref agentskills --help 2>/dev/null && echo "사용 가능" || echo "사용 불가"

uvx가 없는 경우

사용자에게 안내합니다:

`uvx` 명령을 사용할 수 없습니다. `uv`를 설치하면 바로 사용할 수 있습니다:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

또는 내장 스크립트로 대체할 수 있습니다 (스킬 검증 기능은 제외).

### Step 2: 스킬 스캔

#### uvx 사용 가능한 경우 (권장)

```bash
# 모든 스킬의 프롬프트 XML 생성
uvx --from skills-ref agentskills to-prompt {skills_dir}/*/

# 개별 스킬 검증도 함께 수행
for skill in {skills_dir}/*/; do
  uvx --from skills-ref agentskills validate "$skill"
done

to-prompt 출력 결과를 CLAUDE.md용 형식으로 변환합니다 (Step 3 참조).

uvx 사용 불가한 경우 (대체)

내장 스크립트를 사용합니다:

bash skills/skills-ref/scripts/generate-skills-xml.sh {skills_dir}

Step 3: XML 생성 및 CLAUDE.md 반영

스캔 결과를 아래 XML 형식으로 변환하여 CLAUDE.md에 작성합니다.

XML 출력 형식

## Available Skills

<available-skills>

<skill name="{name}" ref="{skills_dir}/{name}">
  <description>{description 첫 문장 (무엇을 하는지)}</description>
  <trigger>{description 트리거 부분 (언제 활성화되는지)}</trigger>
</skill>

</available-skills>

필드 설명

필드	소스	설명
name	frontmatter name	스킬 식별자
ref	디렉토리 상대 경로	스킬 SKILL.md 위치
description	frontmatter description 첫 문장	무엇을 하는지
trigger	frontmatter description 나머지	언제 활성화되는지

실제 예시

## Available Skills

<available-skills>

<skill name="create-skill" ref=".claude/skills/create-skill">
  <description>Claude Code Skill을 생성합니다.</description>
  <trigger>스킬 생성, SKILL.md 작성, 새 스킬 만들기 요청 시 활성화.</trigger>
</skill>

<skill name="add-rules" ref=".claude/skills/add-rules">
  <description>프로젝트에 규칙을 Skill 기반으로 추가하고 기존 규칙을 Skill로 변환합니다.</description>
  <trigger>규칙 추가, 룰 추가, rule 추가, 새 규칙, 컨벤션 추가, 스타일 가이드 추가, 가이드라인 추가, 규칙 변환, rule 통합 요청 시 활성화.</trigger>
</skill>

<skill name="git-commit" ref=".claude/skills/git-commit">
  <description>Git 변경 사항을 분석하여 커밋 메시지를 생성합니다.</description>
  <trigger>커밋, 커밋 메시지 작성, git commit 요청 시 사용.</trigger>
</skill>

</available-skills>

CLAUDE.md 반영 규칙

새 파일인 경우

CLAUDE.md가 없으면 새로 생성합니다:

# Project Guide

## Available Skills

<available-skills>
{generated_xml}
</available-skills>

기존 파일인 경우

CLAUDE.md가 이미 있으면:

1. <available-skills> 섹션이 있으면 → 해당 섹션만 교체
2. <available-skills> 섹션이 없으면 → 파일 끝에 추가

기존 내용을 절대 삭제하지 않습니다. Available Skills 섹션만 갱신합니다.

description 분리 기준

frontmatter description을 <description>과 <trigger>로 분리합니다:

# 원본
description: >
  프로젝트에 규칙을 Skill 기반으로 추가하고 기존 규칙을 Skill로 변환합니다.
  규칙 추가, 룰 추가, rule 추가, 새 규칙, 컨벤션 추가 요청 시 활성화.

# 분리 결과
# description → 첫 문장: "프로젝트에 규칙을 Skill 기반으로 추가하고..."
# trigger → 나머지: "규칙 추가, 룰 추가, rule 추가..."

분리 규칙:

• 첫 번째 . 또는 줄바꿈까지가 description
• 나머지가 trigger
• trigger에 "시 활성화", "시 사용", "요청 시" 등의 패턴이 포함되어 있으면 정확한 분리

완료 보고

## Available Skills 생성 완료

- **스캔 디렉토리**: `{skills_dir}`
- **발견된 스킬**: {count}개
- **CLAUDE.md 경로**: `{claude_md_path}`
- **동작**: 새로 생성 / 기존 섹션 교체 / 끝에 추가

상세 가이드

• XML 형식 상세