Agent Skill

Qwen Code의 기능을 확장하는 Skill을 생성, 관리, 공유하세요.

이 가이드는 Qwen Code에서 Agent Skill을 생성, 사용, 관리하는 방법을 보여줍니다. Skill은 지시사항(및 선택적으로 스크립트/리소스)을 포함한 정리된 폴더를 통해 모델의 효과를 확장하는 모듈식 기능입니다.

사전 요구사항

Qwen Code (최신 버전)
Qwen Code에 대한 기본 이해 (Quickstart)

Agent Skill이란?

Agent Skill은 전문성을 발견 가능한 기능으로 패키징합니다. 각 Skill은 모델이 관련 있을 때 로드할 수 있는 지시사항이 포함된 SKILL.md 파일과 스크립트, 템플릿 등의 선택적 지원 파일로 구성됩니다.

Skill 호출 방식

Skill은 모델이 호출합니다 — 모델이 요청과 Skill의 설명을 기반으로 자율적으로 사용 시점을 결정합니다. 이는 사용자가 명시적으로 /command를 입력하는 사용자 호출 슬래시 명령어와 다릅니다.

Skill을 명시적으로 호출하려면 Skill 이름을 슬래시 명령어로 입력하세요:


/<skill-name>

/를 입력하기 시작하면 자동 완성으로 사용 가능한 Skill과 설명을 탐색할 수 있습니다. /skills 명령어는 Skill 패널을 열어 Skill을 탐색, 검색, 토글, 대화식으로 실행할 수 있습니다.

참고: 이전에 /skills <skill-name>으로 Skill을 실행했다면, 해당 구문은 이제 Skill 패널을 열고 trailing 인수를 무시합니다. Skill을 직접 실행하려면 /<skill-name>을 사용하세요.

이점

워크플로우에 맞게 Qwen Code를 확장
git을 통해 팀 전체에 전문성 공유
반복적인 프롬프팅 감소
복잡한 작업에 여러 Skill 조합

Skill 생성

Skill은 SKILL.md 파일을 포함하는 디렉토리로 저장됩니다.

`/learn`으로 프로젝트 Skill 생성

/learn을 사용하여 기존 지식 소스를 재사용 가능한 프로젝트 Skill로 압축합니다:


/learn https://docs.example.com/api
/learn ~/projects/acme-sdk
/learn Our deploy process: run migrate, deploy the service, then check health

명령어는 일반 에이전트 턴으로 실행되며 프론트매터에 source: learned가 포함된 .qwen/skills/learned-skill-<name>/SKILL.md 아래 결과를 생성합니다. 생성된 지시사항을 사용하거나 공유하기 전에 검토하세요.

/learn은 로컬 또는 직접 링크 .mp4, .webm, .mov, .m4v 비디오도 받습니다. 경로 또는 URL 뒤에 텍스트를 추가하여 생성된 Skill을 튜토리얼의 한 부분에 집중시킬 수 있습니다:


/learn ./tutorial.mp4 focus on the deployment workflow

비디오 학습은 OpenAI 호환 공급자의 비디오 지원 모델이 필요합니다. YouTube 페이지 URL은 직접 비디오 입력이 아닙니다; 비디오를 워크스페이스로 다운로드하고 로컬 경로를 전달하세요.

개인 Skill

개인 Skill은 모든 프로젝트에서 사용 가능합니다. ~/.qwen/skills/에 저장합니다:


mkdir -p ~/.qwen/skills/my-skill-name

개인 Skill 사용 용도:

개별 워크플로우와 선호도
개발 중인 Skill
개인 생산성 도구

프로젝트 Skill

프로젝트 Skill은 팀과 공유됩니다. 프로젝트 내 .qwen/skills/에 저장합니다:


mkdir -p .qwen/skills/my-skill-name

프로젝트 Skill 사용 용도:

팀 워크플로우와 컨벤션
프로젝트별 전문성
공유 유틸리티와 스크립트

프로젝트 Skill은 git에 커밋할 수 있으며 팀원에게 자동으로 사용 가능해집니다.

자동 생성 프로젝트 Skill 유지보수

Qwen Code는 Auto Skill 생성이 비활성화된 동안에도 생성된 프로젝트 Skill의 성공적인 사용을 로컬에서 추적하므로, 유지보수를 다시 활성화할 때 최근에 사용된 skill을 비활성 skill로 오인하지 않습니다. Auto Skill이 활성화되면, 주기적으로 비활성 생성 Skill을 활성 라이브러리에서 이동합니다. SKILL.md 프론트매터에 source: auto-skill이 포함된 .qwen/skills/auto-skill-*로 이름 지어진 디렉토리만 관리됩니다; 개인, 확장, 번들, 수작업 Skill은 절대 선택되지 않습니다.

성공적인 사용 또는 SKILL.md 편집 없이 30일 후, auto-skill은 오래된 것으로 표시됩니다.
90일 후, 전체 디렉토리가 .qwen/archived-skills/로 이동됩니다. 영구 삭제되는 것은 없습니다.
자동 유지보수는 신뢰되는 워크스페이스에서 최대 7일에 한 번 실행됩니다. 새로 관찰된 각 auto-skill은 유지보수가 시작되기 전에 전체 유예 기간을 받습니다.
고정된 auto-skill은 고정 해제될 때까지 자동 오래됨 및 아카이브 전환에서 제외됩니다.
아카이브된 디렉토리 이름은 예약된 상태로 유지되며, 기존 아카이브 대상은 해당 충돌만 건너뛰고 다른 skill의 유지보수를 중지하지 않습니다.

/curator를 사용하여 활성, 오래된, 아카이브된, 고정된 auto-skill을 확인하세요. /curator run --dry-run으로 유지보수 패스를 미리보고, /curator run으로 즉시 적용하고, /curator pin <directory> 또는 /curator unpin <directory>로 skill별 유지보수를 제어하거나, /curator restore <directory>로 아카이브된 auto-skill을 활성 라이브러리로 되돌립니다.

상태 및 dry-run 미리보기는 안전 모드와 신뢰되지 않는 워크스페이스에서 사용 가능합니다. 유지보수 적용, 고정 변경, 아카이브된 auto-skill 복원은 안전 모드 외부의 신뢰되는 워크스페이스가 필요합니다.

`SKILL.md` 작성

YAML 프론트매터와 Markdown 콘텐츠가 포함된 SKILL.md 파일을 생성합니다:


---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
priority: 10
---
 
# Your Skill Name
 
## Instructions
Provide clear, step-by-step guidance for Qwen Code.
 
## Examples
Show concrete examples of using this Skill.

필드 요구사항

Qwen Code는 현재 다음을 검증합니다:

name은 /^[\p{L}\p{N}_:.-]+$/u와 일치하는 비어 있지 않은 문자열 — 유니코드 문자와 숫자(CJK / 키릴 / 악센트 Latin 모두 가능) 그리고 _, :, ., -. 공백, 슬래시, 대괄호 및 기타 구조적으로 안전하지 않은 문자는 파싱 시 거부됩니다.
description은 비어 있지 않은 문자열
priority는 선택 사항. 존재하면 유한한 숫자여야 합니다. 높은 값은 /skills 목록에서만 먼저 정렬됩니다 — 슬래시 명령어 자동 완성(/ 입력)과 /help 사용자 정의 명령어 보기는 알파벳 순서를 유지하므로, 우선순위가 높은 Skill이 내장 명령어를 재정렬하지 않습니다. 생략되거나 잘못된 값은 설정되지 않은 것으로 처리되며 0과 동일하게 동작합니다.

권장 컨벤션:

공유 가능한 이름에는 하이픈이 포함된 소문자 ASCII 선호 (예: tsx-helper)
description을 구체적으로 작성: Skill이 무엇을 하는지와 언제 사용해야 하는지(사용자가 자연스럽게 언급할 키워드) 포함
/skills에서 기본 알파벳 순서보다 먼저 나타나야 하는 Skill에 priority를 신중하게 사용. 음수 우선순위 허용되며 설정되지 않은 Skill 아래로 정렬됩니다.

선택 사항: 파일 경로로 Skill 제한 (`paths:`)

코드베이스의 특정 부분에만 관련되는 Skill의 경우, glob 패턴의 paths: 목록을 추가합니다. 일치하는 파일에 도구 호출이 접근할 때까지 Skill은 모델의 사용 가능한 skill 목록에 표시되지 않습니다:


---
name: tsx-helper
description: React TSX component helper
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

참고:

Glob은 프로젝트 루트를 기준으로 picomatch 와 매칭됩니다; 프로젝트 루트 외부의 파일은 절대 활성화를 트리거하지 않습니다.
경로로 제한된 Skill은 일치하는 파일이 접근되면 세션이 끝날 때까지 활성화된 상태로 유지됩니다. 새 세션 또는 Skill 파일 편집으로 트리거되는 refreshCache가 활성화를 재설정합니다.
paths:는 모델 검색만 제한하며 SkillTool 목록 수준에서만 제한됩니다. user-invocable: false가 설정되지 않은 한, /<skill-name> 또는 /skills 피커를 통해 경로 제한 Skill을 항상 직접 호출할 수 있습니다 — 해당 사용자 경로는 활성화 상태와 관계없이 Skill 본문을 실행합니다. 하지만 모델 측은 일치하는 파일이 접근될 때까지 제한된 상태로 유지됩니다: 슬래시 호출이 모델 측 활성화를 잠금 해제하지 않으므로, 모델이 호출에서 체인하도록 하려면(skill 자체 Skill { skill: ... } 호출), 먼저 skill의 paths:와 일치하는 파일에 접근하세요.
paths:와 disable-model-invocation: true를 조합하는 것은 허용되지만 게이트가 효과가 없습니다 — Skill은 어쨌든 모델에서 숨겨지므로 경로 활성화가 이를 광고하지 않습니다.

선택 사항: 사용자 및 모델 호출 제어

Skill은 기본적으로 사용자 호출 가능합니다. 직접 슬래시 명령어 사용에서 Skill을 숨기면서 모델 호출에 대해 사용 가능하게 유지하려면 user-invocable: false를 설정합니다:


---
name: model-only-helper
description: Helper the model can call when appropriate
user-invocable: false
---

이렇게 하면 /<skill-name> 호출과 /skills 피커 결과에서 Skill이 제거됩니다. 모델에서 Skill을 숨기지 않습니다.

직접 사용자 호출을 유지하면서 모델 호출에서 Skill을 숨기려면 disable-model-invocation: true를 설정합니다:


---
name: manual-helper
description: Helper you invoke manually
disable-model-invocation: true
---

두 필드를 모두 조합할 수 있지만, Skill은 일반적인 사용자 또는 모델 호출 경로로 접근할 수 없게 됩니다.

선택 사항: 규칙을 결정적으로 강제 (`hooks:`)

SKILL.md 본문의 모든 내용은 모델에 대한 지시사항입니다: 프롬프트 텍스트이므로 따를지 여부는 모델에 달려 있습니다. 모델이 어떻게 결정하든 규칙이 반드시 유지되어야 하는 경우 — 필수 값이 주입되지 않으면 실행을 거부하거나 보호된 경로를 절대 건드리지 않아야 하는 경우 — 프론트매터에 hook을 선언하세요. hook은 코드로 실행되므로 모델의 협력에 의존하지 않습니다:


---
name: gated-skill
description: Calls the downstream CLI using a runtime-injected session ID
hooks:
  PreToolUse:
    - matcher: run_shell_command
      hooks:
        - type: command
          command: '"$QWEN_SKILL_ROOT/scripts/gate-session-id.sh"'
---

$QWEN_SKILL_ROOT는 Skill 자체의 디렉토리로 설정되므로, hook 명령어는 SKILL.md와 함께 제공되는 파일을 참조할 수 있습니다. 명령어 문자열은 셸에 전달되므로 내부 따옴표를 유지하세요: 따옴표가 없으면 공백이 포함된 프로젝트 경로가 두 단어로 분할되어 게이트가 실행되지 않습니다. 스크립트를 실행 가능하게 (chmod +x) 만들 수도 있습니다. 두 실수 모두 같은 방식으로 개방적으로 실패합니다: 도구 호출이 진행되며, 게이트가 실행되지 않았다는 메시지가 트랜스크립트나 로그에 나타나지 않습니다. PreToolUse hook은 종료 코드 2로 종료되면(표준 오류가 모델에 이유로 전달됨) 또는 hookSpecificOutput.permissionDecision: "deny"를 출력하면 도구 호출을 차단합니다:


#!/usr/bin/env bash
if [ -z "${DOWNSTREAM_SESSION_ID:-}" ]; then
  echo "Required input DOWNSTREAM_SESSION_ID is not available. Cannot proceed." >&2
  exit 2
fi
exit 0

참고:

hook은 Skill이 호출될 때 등록되며 세션이 끝날 때까지 유지됩니다. 이는 두 호출 경로 모두에 해당됩니다 — 모델이 Skill을 호출하든 /<skill-name>을 입력하든.
세션 hook은 인메모리에만 존재하므로 --continue / --resume으로 세션을 재개해도 복원되지 않습니다. 두 호출 경로 모두 동일합니다. Skill의 지시사항은 리플레이된 대화와 함께 돌아올 수 있지만 이를 강제해야 하는 hook은 사라집니다 — 재개 후 Skill을 다시 실행하여 게이트를 다시 활성화하세요.
등록은 멱등합니다: Skill을 다시 호출해도 중복 hook이 쌓이지 않습니다.
도구 이벤트에 항상 명시적인 matcher:를 지정하세요. 생략되면 빈 패턴으로 저장되어 ^로 컴파일되며 어떤 도구 이름과도 매칭되지 않습니다 — hook은 등록되지만 절대 실행되지 않으며 이를 알리는 메시지도 없습니다. 모든 도구를 의미한다면 *를 사용하세요.
command:는 플랫폼 셸을 통해 실행됩니다: macOS와 Linux에서는 bash, Windows에서는 Git Bash가 감지되면(MSYSTEM/TERM), 그렇지 않으면 cmd.exe 또는 PowerShell. 위 예시는 POSIX 셸입니다 — cmd.exe에서는 $QWEN_SKILL_ROOT가 확장되지 않고 .sh 스크립트가 실행 가능하지 않으므로 게이트가 개방적으로 실패합니다. hook은 shell: bash를 설정하여 bash를 강제할 수 있지만 PATH의 bash로 해석되므로, Git Bash 외부의 Windows에서는 실제로 사용 중인 셸에 맞게 게이트를 작성하세요.
hook을 비활성화하는 세션은 어느 것도 등록하지 않습니다 — disableAllHooks, 안전 모드, ACP 클라이언트의 skipHooks. 이러한 세션에서도 Skill의 본문과 allowedTools는 여전히 적용되지만 게이트는 적용되지 않으므로, hook 강제에 의존하는 규칙은 여기서 강제되지 않습니다. Bare 모드는 더 나아가서: 어떤 Skill도 발견되지 않으므로 본문도 allowedTools도 없습니다.
프로젝트 Skill의 hook은 저장소에서 제공한 명령어를 실행하므로 신뢰되는 폴더에서만 등록되며, hook이 실행될 때마다 그리고 권한이 결정될 때마다 신뢰가 다시 읽힙니다. IDE 컴패니언이 연결되어 있으면 이 값은 실시간입니다: 신뢰를 취소하면 다음 도구 호출에서 이미 등록된 게이트가 침묵화되고 — Skill의 allowedTools도 중단됩니다 — 재시작 없이. IDE 연결이 없으면 CLI가 시작될 때 값이 고정되므로 CLI의 신뢰 대화상자를 통한 변경은 재시작 시 적용됩니다. 신뢰 부여는 소급 등록하지 않습니다: Skill을 다시 호출하세요.
hooks:는 프로젝트, 사용자 및 번들 Skill에서 읽힙니다. 확장이 제공하는 Skill은 지원하지 않습니다; 대신 확장 자체의 매니페스트 수준 hook을 사용하세요.
전체 이벤트 목록, matcher 구문 및 출력 형식은 Hooks를 참조하세요.

지원 파일 추가

SKILL.md와 함께 추가 파일을 생성합니다:


my-skill/
├── SKILL.md (필수)
├── reference.md (선택 문서)
├── examples.md (선택 예시)
├── scripts/
│   └── helper.py (선택 유틸리티)
└── templates/
    └── template.txt (선택 템플릿)

SKILL.md에서 이 파일들을 참조합니다:


For advanced usage, see [reference.md](reference.md).
 
Run the helper script:
 
```bash
python scripts/helper.py input.txt
```

사용 가능한 Skill 보기

Qwen Code는 다음에서 Skill을 발견합니다:

개인 Skill: ~/.qwen/skills/
프로젝트 Skill: .qwen/skills/
확장 Skill: 설치된 확장이 제공하는 Skill
번들 Skill: Qwen Code에 포함된 Skill

확장 Skill

확장은 활성화되면 사용 가능해지는 커스텀 skill을 제공할 수 있습니다. 이 skill은 확장의 skills/ 디렉토리에 저장되며 개인 및 프로젝트 skill과 동일한 형식을 따릅니다.

확장 skill은 확장이 설치되고 활성화되면 자동으로 발견되고 로드됩니다.

어떤 확장이 skill을 제공하는지 확인하려면 확장의 qwen-extension.json 파일에서 skills 필드를 확인하세요.

사용 가능한 Skill을 보려면 Qwen Code에게 직접 물어보세요:


What Skills are available?

주의 — 모델 vs. 사용자 뷰. 모델에게 물어보면 모델이 현재 볼 수 있는 Skill만 표시됩니다. Skill이 paths:를 사용하면(위 “선택 사항: 파일 경로로 Skill 제한” 참조), 일치하는 파일이 접근될 때까지 해당 목록에 표시되지 않습니다. /skills 슬래시 명령어는 직접 호출할 수 있는 Skill을 표시합니다; user-invocable: false가 있는 Skill은 디스크에 표시된 상태로 유지되며 모델에게 여전히 보일 수 있습니다.

또는 슬래시 명령어로 사용자 호출 가능 목록을 탐색합니다(아직 활성화되지 않은 경로 제한 Skill 포함):


/skills

또는 파일시스템을 검사합니다:


# 개인 Skill 나열
ls ~/.qwen/skills/
 
# 프로젝트 Skill 나열 (프로젝트 디렉토리에 있는 경우)
ls .qwen/skills/
 
# 특정 Skill의 내용 보기
cat ~/.qwen/skills/my-skill/SKILL.md

Skill 테스트

Skill을 생성한 후, 설명과 일치하는 질문을 하여 테스트합니다.

예시: 설명에 “PDF files”가 언급된 경우:


Can you help me extract text from this PDF?

모델이 요청과 일치하면 자율적으로 Skill을 사용합니다 — 명시적으로 호출할 필요가 없습니다.

Skill 디버그

Qwen Code가 Skill을 사용하지 않으면 다음 일반적인 문제를 확인하세요:

설명을 구체적으로 작성

너모 모호한 경우:


description: Helps with documents

구체적인 경우:


description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.

파일 경로 확인

개인 Skill: ~/.qwen/skills/<skill-name>/SKILL.md
프로젝트 Skill: .qwen/skills/<skill-name>/SKILL.md


# 개인
ls ~/.qwen/skills/my-skill/SKILL.md
 
# 프로젝트
ls .qwen/skills/my-skill/SKILL.md

YAML 구문 확인

잘못된 YAML은 Skill 메타데이터가 올바르게 로드되는 것을 방지합니다.


cat SKILL.md | head -n 15

확인 사항:

1행에 시작 ---
Markdown 콘텐츠 전에 종료 ---
유효한 YAML 구문 (탭 없음, 올바른 들여쓰기)

오류 보기

디버그 모드로 Qwen Code를 실행하여 Skill 로드 오류를 확인합니다:


qwen --debug

팀과 Skill 공유

프로젝트 리포지토리를 통해 Skill을 공유할 수 있습니다:

.qwen/skills/ 아래에 Skill 추가
커밋 및 푸시
팀원이 변경 사항을 pull


git add .qwen/skills/
git commit -m "Add team Skill for PDF processing"
git push

Skill 업데이트

SKILL.md를 직접 편집합니다:


# 개인 Skill
code ~/.qwen/skills/my-skill/SKILL.md
 
# 프로젝트 Skill
code .qwen/skills/my-skill/SKILL.md

일반 세션 중에 Qwen Code는 개인 및 프로젝트 Skill 디렉토리를 감시합니다. Skill을 추가, 편집, 제거하면 짧은 지연 후 Skill 목록과 호출 상태가 자동으로 새로 고쳐집니다. Bare 모드는 이 감시자를 시작하지 않으므로 해당 모드에서 Skill 변경 사항을 로드하려면 Qwen Code를 재시작하세요.

Skill 제거

Skill 디렉토리를 삭제합니다:


# 개인
rm -rf ~/.qwen/skills/my-skill
 
# 프로젝트
rm -rf .qwen/skills/my-skill
git commit -m "Remove unused Skill"

모범 사례

Skill을 집중적으로 유지

하나의 Skill은 하나의 기능을 다루어야 합니다:

집중적: “PDF form filling”, “Excel analysis”, “Git commit messages”
너무 광범위: “Document processing” (더 작은 Skill로 분할)

명확한 설명 작성

구체적인 트리거를 포함하여 모델이 Skill 사용 시점을 발견하도록 돕습니다:


description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.

팀과 테스트

Skill이 예상될 때 활성화되나요?
지시사항이 명확한가요?
누락된 예시나 엣지 케이스가 있나요?