skills-ref

Skills Ref

Scans the skills directory and adds to CLAUDE.md <available-skills> Creates an XML section.

CRITICAL: Ask the user first

This skill must, before any analysis or command execution, ask the user the following two things. Never proceed without the user's response.

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

• skills/ Do not assume the same default. You must ask the user.
• The skills directory differs for each repo:
  • General project → .claude/skills/
  • Skill library repo → skills/ (for distribution), .claude/skills/ (for the project itself)
  • Monorepo → packages/{pkg}/.claude/skills/

Proceed with the workflow below only after the user tells you the directory.

---

Workflow

Step 1: Check the uvx execution environment

uvx로 skills-refCheck whether it can be run:

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

If uvx is not available

Guide the user:

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

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

Alternatively, you can fall back to the built-in script (excluding the skill validation feature).

### 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 Convert the output into the format for CLAUDE.md (see Step 3).

If uvx is unavailable (fallback)

Use the built-in script:

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

Step 3: Generate XML and apply to CLAUDE.md

Convert the scan results into the XML format below and write them to CLAUDE.md.

XML output format

## Available Skills

<available-skills>

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

</available-skills>

Field descriptions

Field	Source	Description
name	frontmatter name	Skill identifier
ref	Directory relative path	Skill SKILL.md location
description	frontmatter description First sentence	What it does
trigger	frontmatter description Rest	When it is activated

Real examples

## 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 application rules

If it is a new file

If CLAUDE.md does not exist, create it:

# Project Guide

## Available Skills

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

If it is an existing file

If CLAUDE.md already exists:

1. <available-skills> If the section exists → Replace only that section
2. <available-skills> If the section does not exist → Append to the end of the file

Never delete existing content. Update only the Available Skills section.

description separation criteria

frontmatter description을 <description>과 <trigger>Split by :

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

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

Separation rules:

• The first . Or up to the newline is the description
• The rest is the trigger
• If the trigger contains patterns such as "activate when", "use when", "when requested", split precisely

Completion report

## Available Skills 생성 완료

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

Detailed guide

• XML format details