JMBargueno/skanvil

skanvil은(는) 무엇을 하나요?

목적

skanvil CLI를 통해 스킬 라이브러리를 변경하여, 스킬 폴더, SKILL.md 프론트매터, README 인덱스 및 라이브러리 규칙이 일관성을 유지하고 검증을 통과하도록 합니다.

이 스킬을 활성화해야 하는 경우

• 저장소에 .skanvilrc.json, SKILL.md 파일이 있는 skills/ 폴더, 또는 package.json에 skanvil이 있을 때.
• 사용자가 스킬을 추가, 작성, 이름 변경, 이동, 제목 변경, 설명 변경, 삭제, 나열, 검증 또는 인덱싱을 요청할 때.
• skanvil validate, npm test 또는 CI가 skanvil 진단으로 실패할 때.
• 사용자가 다른 프로젝트의 Claude Code, GitHub Copilot 또는 Codex에서 라이브러리의 스킬을 사용할 수 있도록 하려 할 때.

지침

1. 상황 파악

1. .skanvilrc.json을 읽습니다. 이 파일은 카테고리(id, 폴더 prefix, README title, aliases), 필수 섹션, 플레이스홀더 및 규칙 심각도를 정의합니다. 파일이 없으면 기본 프리셋(front-, back-, 접두사 없는 transversal(기본값), _internal)을 사용합니다.
2. npx skanvil list --json을 실행하여 각 스킬의 카테고리, README 존재 여부 및 유효성을 확인합니다.
3. npx skanvil validate --json을 실행하여 변경 전에 이미 존재하는 문제점을 파악합니다.

2. 황금률

• 스킬 폴더를 수동으로 이름 변경, 이동 또는 삭제하지 말고, README 인덱스를 수동으로 편집하지 마십시오. skanvil edit을 사용하세요. 이 명령어는 폴더, 프론트매터 name, # 제목 및 README 항목을 동기화하고, 실패 시 롤백합니다.
• 스킬 폴더를 수동으로 생성하지 마십시오. skanvil add를 사용하세요. 이 명령어는 카테고리 접두사, 템플릿, 프론트매터 메타데이터 및 README 항목을 적용합니다.
• 비대화형 셸에서는 항상 모든 옵션을 전달하십시오. add에는 --type, --name 및 --description이 필요합니다. edit --remove에는 --yes가 필요합니다. 그렇지 않으면 명령어가 프롬프트를 표시하거나 TTY가 없으면 실패합니다.
• 인수 없이 skanvil을 실행하거나 skanvil wizard를 실행하지 마십시오. 이 명령어는 사람을 위한 대화형 메뉴를 엽니다. 아래의 명시적 명령어를 사용하세요. 사용자가 메뉴를 선호하는 경우 직접 npx skanvil을 실행하도록 제안하십시오.
• 출력을 구문 분석해야 할 때마다 --json을 추가하십시오. 데이터는 stdout으로, 경고 및 오류는 stderr로 전달됩니다.
• 모든 변경 후 npx skanvil validate를 실행하고 오류 없이 완료하십시오. 종료 코드 1은 오류를 의미하거나 --strict 사용 시 경고를 의미합니다.
• skanvil이 PATH에 없는 한 모든 명령어 앞에 npx를 붙이십시오. 다른 폴더의 라이브러리를 대상으로 하려면 -C <path>를 사용하십시오.

3. 일반적인 작업

스킬을 생성한 다음 내용을 작성합니다.

npx skanvil add --type <category> --name "<짧은 이름>" \
  --description "<하는 일>. <트리거 상황>일 때 사용하세요."

그런 다음 skills/<prefix><name>/SKILL.md를 편집합니다:

• 모든 필수 섹션을 구체적이고 실행 가능한 내용으로 채웁니다.
• 모든 일반 템플릿 문장을 대체합니다. 그렇지 않으면 validate가 template-unchanged 경고를 보고하고, validate --strict(라이브러리의 npm test)가 실패합니다.
• 긴 자료는 references/로 이동하고, 존재하는 파일에만 링크합니다(broken-references).

해당 폴더가 비어 있을 경우 --no-scripts, --no-assets 또는 --no-references를 사용하십시오. .skanvil/templates/의 사용자 정의 템플릿을 사용하려면 --template <name>을 사용하십시오.

스킬의 이름을 변경하거나 이동합니다.

npx skanvil edit <skill> --rename <new-name>          # 접두사가 자동으로 다시 적용됩니다
npx skanvil edit <skill> --type <other-category>      # 새 접두사, README 섹션, 메타데이터
npx skanvil edit <skill> --title "<Title>" --description "<text>"

--rename은 기본 이름을 사용합니다: edit front-a --rename b는 front-b를 생성합니다.

스킬을 삭제합니다. 먼저 사용자에게 확인하십시오. 이 작업은 영구적입니다.

npx skanvil edit <skill> --remove --yes

검증 오류를 수정합니다.

1. npx skanvil doctor --fix를 실행합니다. README 항목, name 불일치, 프론트매터의 탭을 수정하고 tools를 allowed-tools로 변환합니다.
2. SKILL.md를 편집하여 나머지 오류를 수정합니다. 아래 진단표를 참조하세요.
3. npx skanvil validate를 다시 실행합니다.

.skanvilrc.json에서 카테고리 제목을 변경한 후 README 인덱스를 다시 빌드합니다:

npx skanvil index          # 인덱스 섹션을 다시 작성합니다
npx skanvil index --check  # 확인만 수행합니다 (CI용)

프로젝트에 스킬을 설치합니다.

npx skanvil sync <project-dir> -C <library-dir> --target claude,copilot --dry-run   # 미리보기
npx skanvil sync <project-dir> -C <library-dir> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # 설치된 패키지

대상:

• claude는 .claude/skills에 설치합니다.
• copilot은 .github/skills에 설치합니다.
• agents 및 codex는 .agents/skills에 설치합니다.
• 사용자 지정 경로는 프로젝트 내의 폴더여야 합니다.
• --global (프로젝트 디렉토리 없이)은 사용자의 ~/.claude/skills, ~/.copilot/skills 또는 ~/.agents/skills에 설치합니다. 사용자가 모든 프로젝트에서 사용 가능한 스킬을 요청할 때만 사용하십시오.

동기화 동작:

• 자신이 설치하지 않은 폴더는 덮어쓰지 않습니다.
• 라이브러리에서 제거된 스킬을 정리합니다.
• --force가 제공되지 않으면 검증 오류가 있는 스킬을 건너뜁니다.
• _internal 스킬은 게시하지 않습니다.

카테고리를 추가하거나 변경합니다. .skanvilrc.json에서 categories를 편집합니다:

• 정확히 하나의 카테고리가 "default": true이고 접두사가 없어야 합니다.
• 다른 모든 카테고리는 _ 또는 -로 끝나는 케밥-케이스 접두사를 가져야 합니다.
• 어떤 접두사도 다른 접두사로 시작해서는 안 됩니다.

그런 다음 edit --type으로 기존 스킬을 이동하고 skanvil index를 실행합니다.

4. 좋은 스킬 콘텐츠 작성법

• description 은 스킬이 무엇을 하는지와 에이전트가 볼 트리거 키워드를 포함하여 언제 사용하는지를 설명합니다. 최대 1024자여야 합니다.
• name 은 폴더 이름과 일치해야 합니다: 소문자, 숫자 및 단일 하이픈만 사용하며 최대 64자입니다.
• 본문: SKILL.md를 500줄 미만으로 유지합니다. 지침은 번호가 매겨진 검증 가능한 단계로 작성하고, 예제, 엣지 케이스 및 긴 체크리스트는 references/(한 수준 깊이)에 넣습니다.
• 플레이스홀더: 채우기 텍스트를 남겨두지 마십시오. validation.placeholders의 항목(할 일 표시자, 더미 라틴어 텍스트, "추후 결정" 메모)은 검증에 실패합니다.
• metadata: 문자열 값만 사용하므로, 숫자는 version: "1.0"과 같이 따옴표로 묶습니다.
• allowed-tools: 목록이 아닌 공백으로 구분된 문자열입니다.

5. 진단 → 수정

규칙	수정
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix, 또는 폴더 이름이 잘못된 경우 edit --rename
frontmatter-tabs, tools-field	doctor --fix
frontmatter	--- 줄 사이의 YAML을 수정합니다(: 또는 #를 포함하는 값은 따옴표로 묶음).
required-sections	validation.requiredSections에 나열된 누락된 ## 섹션을 추가합니다.
placeholders	플레이스홀더 텍스트를 실제 내용으로 대체합니다.
description-length, max-lines	줄입니다. 세부 정보는 references/로 이동합니다.
metadata-format	문자열이 아닌 값을 따옴표로 묶습니다.
duplicate-name	두 폴더가 동일한 name을 공유합니다: edit --rename으로 하나의 이름을 변경합니다.
broken-references	참조된 파일을 생성하거나 링크를 수정합니다(경로는 스킬 기준 상대 경로).
template-unchanged	일반적인 뼈대 문장을 스킬별 지침으로 다시 작성합니다.

모든 명령 옵션, 구성 스키마 및 JSON 출력 형태는 references/REFERENCE.md를 참조하십시오.

출력 형식

사용자에게 보고합니다:

• 실행한 skanvil 명령어
• 생성, 변경 또는 제거된 스킬 및 해당 폴더 이름
• 최종 skanvil validate 결과(오류 및 경고) 및 사용자가 결정해야 할 사항

품질 기준

• 모든 구조적 변경은 skanvil add 또는 skanvil edit을 통해 이루어졌습니다. 수동 폴더 이름 변경이나 README 인덱스 편집이 없습니다.
• npx skanvil validate가 오류를 보고하지 않고 npx skanvil index --check가 통과합니다.
• 새로 생성되거나 편집된 스킬은 트리거가 포함된 구체적인 설명을 가지며 템플릿 채우기나 플레이스홀더가 없습니다.
• 삭제 및 다른 프로젝트로의 동기화는 사용자와 확인되었습니다.