스킬

스킬 (Skills)

스킬은 작업이 스킬의 설명과 일치할 때 에이전트가 온디맨드로 로드할 수 있는 특화 지침을 제공해요.

출처: 문서

본문

스킬이 동작하는 방식 (How Skills Work)

  • Docker Agent가 표준 디렉터리에서 SKILL.md 파일을 스캔
  • 스킬 메타데이터(이름, 설명)가 에이전트의 시스템 프롬프트에 주입
  • 사용자 요청이 스킬과 일치하면 에이전트가 전체 지침을 읽음
  • 에이전트가 스킬의 상세 지침을 따라 작업 완료

스킬 활성화 (Enabling Skills)

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    skills: true
    toolsets:
      - type: filesystem # required for reading skill files

Tip 스킬은 프로젝트 전반에 적용되는 팀 특화 워크플로(PR 검토, 배포, 코딩 표준)를 인코딩하는 데 완벽해요.

스킬 필터링 (Filtering Skills)

skills 필드는 목록도 받아, 발견된 모든 것을 노출하는 대신 에이전트를 특정 하위 집합으로 제한할 수 있게 해요. 목록 항목은 자동으로 분류돼요:

  • "local" 또는 어떤 http:// / https:// URL → 스킬을 로드할 소스
  • 다른 어떤 문자열 → 포함할 스킬의 이름

이름만 주어질 때는 로컬 소스가 기본으로 사용돼요.

agents:
  # Load every discovered local skill (same as `skills: true`).
  full:
    skills: true

  # Load local skills, but only expose "commit" and "poem".
  scoped:
    skills:
      - commit
      - poem

  # Combine an explicit source with a name filter.
  remote_filtered:
    skills:
      - https://skills.example.com
      - commit

  # Disable skills entirely.
  none:
    skills: false

어떤 발견된 스킬과도 일치하지 않는 이름은 시작 시 경고로 로그되지만 그 외에는 무시돼요.

인라인 스킬 (Inline Skills)

파일과 URL에서 스킬을 로드하는 대신(또는 그와 함께) 에이전트 구성에서 스킬을 직접 정의할 수 있어요. 인라인 스킬은 skills 목록의 매핑 항목으로, 위의 문자열 항목과 자유롭게 섞여요:

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    skills:
      - name: changelog
        description: Write a concise changelog entry from a diff or description.
        instructions: |
          Produce a single changelog entry in Keep a Changelog style.
          Pick the right category (Added, Changed, Fixed, Removed) and write
          one imperative sentence summarising the user-visible change.

      # A fork-mode inline skill runs in an isolated sub-agent.
      - name: triage
        description: Triage a bug report in an isolated context.
        context: fork
        instructions: |
          Restate the problem, list likely root causes most-probable-first,
          and propose the smallest reproduction and next concrete action.

      # Inline skills mix freely with sources and name filters.
      - local
    toolsets:
      - type: filesystem

인라인 스킬은 자신의 본문을 구성 자체에 실으므로 SKILL.md 파일과 파일시스템 소스가 필요 없어요. 그것들은 항상 노출돼요 — 이름 필터는 파일 기반 및 URL 기반 스킬에만 적용돼요. 인라인 스킬은 에이전트 YAML 안에서 이동하므로 --sandbox 모드에서도 키트 스테이징 없이 동작하고, share push 로 에이전트와 공유될 수 있어요.

인라인 스킬 필드 (Inline Skill Fields)

Field Required Description
name Yes read_skill / run_skill 및 /<name> 명령이 사용하는 스킬 식별자
description Yes 스킬 매칭을 위해 에이전트에 표시되는 짧은 설명
instructions Yes 스킬 본문 (SKILL.md가 그 frontmatter 아래에 담을 것)
context No 스킬을 격리된 하위 에이전트로 실행하려면 fork 로 설정
model No fork 모드 스킬 실행 동안 사용할 모델 재정의
allowed_tools No fork 모드 스킬의 경우, 이름이 항목(glob 또는 정확히)과 일치하는 부모 도구로 하위 세션을 제한. Scoping a fork skill's tools 참고.
toolsets No fork 모드 스킬의 경우, 상속된 도구 위에 하위 세션에 노출할 최상위 toolset 이름.

Note 인라인 vs. 파일 기반 스킬 인라인 스킬은 YAML에 맞는 SKILL.md 형식의 하위 집합을 지원해요. 지원 파일을 묶을 수 없고(read_skill_file 없음) !command` 확장을 쓸 수 없어요. 묶인 리소스나 실행 가능한 헬퍼가 필요한 스킬에는 SKILL.md 디렉터리를 대신 사용하세요.

SKILL.md 형식 (SKILL.md Format)

---
name: create-dockerfile
description: Create optimized Dockerfiles for applications
license: Apache-2.0
metadata:
  author: my-org
  version: "1.0"
---

# Creating Dockerfiles

When asked to create a Dockerfile:

1. Analyze the application type and language
2. Use multi-stage builds for compiled languages
3. Minimize image size by using slim base images
4. Follow security best practices (non-root user, etc.)

Frontmatter 필드 (Frontmatter Fields)

Field Required Description
name Yes 고유한 스킬 식별자
description Yes 스킬 매칭을 위해 에이전트에 표시되는 짧은 설명
context No 스킬을 격리된 하위 에이전트로 실행하려면 fork 로 설정 (아래 참고)
model No 스킬을 하위 에이전트로 실행할 때 사용할 모델 재정의 (fork만)
allowed-tools No fork 모드 스킬의 경우, 이름이 항목(YAML 목록 또는 쉼표 구분 문자열)과 일치하는 부모 도구로 하위 세션 제한. Scoping a fork skill's tools 참고.
toolsets No fork 모드 스킬의 경우, 하위 세션에 노출할 최상위 toolset 이름(YAML 목록 또는 쉼표 구분 문자열).
license No 라이선스 식별자 (예: Apache-2.0)
compatibility No 자유 텍스트 호환성 참고
metadata No 임의의 키-값 쌍 (예: author, version)

스킬을 하위 에이전트로 실행 (Running a Skill as a Sub-Agent)

기본적으로 에이전트가 스킬을 호출하면 지침을 인라인으로 자신의 대화에 읽어요. 복잡한 다단계 스킬의 경우 이것은 에이전트의 컨텍스트 창 중 큰 부분을 소비하고 중간 도구 호출로 부모 대화를 오염시킬 수 있어요.

SKILL.md frontmatter에 context: fork 를 추가하면 에이전트가 스킬을 대신 격리된 하위 에이전트에서 실행하도록 지시해요:

---
name: bump-go-dependencies
description: Update Go module dependencies one by one
context: fork
---

# Bump Dependencies

1. List outdated deps
2. Update each one, run tests, commit or revert
3. Produce a summary table

에이전트가 context: fork 스킬과 일치하는 작업을 만나면 read_skill 대신 run_skill 도구를 사용해요. 이것은:

  • 스킬 콘텐츠를 시스템 프롬프트로, 호출자 작업을 사용자 메시지로 하여 자식 세션을 생성
  • 컨텍스트 창을 격리 — 하위 에이전트는 자체 대화 기록을 가지므로, 긴 도구 호출 체인이 부모의 토큰 예산을 잡아먹지 않음
  • 결과를 접기 — 하위 에이전트의 최종 답변만 도구 결과로 부모에게 반환
  • 부모의 모델과 도구를 상속 — 하위 에이전트는 부모 에이전트에 사용 가능한 모든 도구를 사용할 수 있음 (allowed_tools / toolsets 로 범위 지정, Scoping a fork skill's tools 참고)

Tip context: fork 언제 쓸까 많은 단계, 무거운 도구 사용이 포함되거나 메인 대화를 어지럽히지 않아야 하는 스킬 — 예를 들어 의존성 업그레이드, 큰 리팩터, 코드 생성 파이프라인 — 에는 context: fork 를 사용하세요.

fork 스킬용 모델 재정의 (Overriding the model for a fork skill)

Fork 스킬은 하위 세션 동안 부모 에이전트와 다른 모델을 사용하도록 frontmatter에 model 필드를 선언할 수 있어요. 이것은 스킬을 더 빠르고, 저렴하거나, 더 특화된 모델로 처리하는 것이 최상일 때 유용해요 — 예를 들어 리팩터에는 강력한 추론 모델, 일상 사무 작업에는 빠른 모델. 재정의는 스킬이 실행되는 동안에만 적용되고, 부모 에이전트는 자신의 모델을 유지해요.

모델 값은 에이전트 구성의 이름 있는 모델 또는 인라인 provider/model 참조(그리고 나머지 에이전트 구성과 같은 쉼표 구분 alloy 구문)를 받아요:

---
name: bump-go-dependencies
description: Update Go module dependencies one by one
context: fork
model: openai/gpt-4o-mini
---

# Bump Dependencies

1. ...

모델 참조를 해석할 수 없으면(알 수 없는 이름, 자격 증명 누락, 런타임이 모델 전환에 대해 구성되지 않음 등) 스킬은 에이전트의 현재 활성 모델(구성된 기본값, 또는 사용자가 모델 선택기로 이전에 설정한 재정의)로 폴백하고 경고가 로그돼요.

스킬이 완료되면 에이전트의 이전 모델이 복원돼요 — 단, 그 사이에 다른 누군가가 모델을 바꾸지 않았을 때만. fork 스킬이 실행되는 동안 사용자가 TUI 모델 선택기로 모델을 전환하면, 그 선택이 보존돼요(지연된 복원이 no-op이 됨).

fork 스킬의 도구 범위 지정 (Scoping a fork skill's tools)

기본적으로 fork 스킬은 부모 에이전트의 전체 도구 집합을 상속해요. 두 가지 선택적 필드로 하위 세션이 사용할 수 있는 것을 범위 지정할 수 있어요. 둘 다 fork 모드 스킬에만 적용되고 인라인이든 SKILL.md 파일이든 같게 동작해요.

allowed_tools(frontmatter: allowed-tools)는 상속된 도구에 대한 허용 목록이에요: 이름이 항목과 일치하는 도구만 유지되고, 나머지 다른 모든 것은 하위 세션에서 숨겨져요. 항목은 glob 패턴(예: read_*)을 지원하고 그 외에는 정확히 일치해요. 이것은 Claude-Code 호환 allowed-tools 필드로, 이제 단지 기록되는 게 아니라 fork 스킬에 대해 강제돼요.

toolsets 는 이름으로 재사용 가능한 최상위 toolset 을 참조해요. 참조된 toolset은 상속된 도구 위에 하위 세션에 노출되고, allowed_tools 필터를 우회해요(스킬이 명시적으로 그것들을 요청했기 때문).

toolsets:
  web:
    type: fetch

agents:
  root:
    model: openai/gpt-4o
    instruction: You are a helpful assistant.
    toolsets:
      - type: filesystem
      - type: shell
    skills:
      # Inherits the parent tools but is restricted to read-only filesystem
      # access while it runs — shell and write tools are hidden.
      - name: audit
        description: Review the repository layout without modifying anything.
        context: fork
        allowed_tools:
          - read_file
          - list_directory
          - directory_tree
        instructions: Inspect the repository structure and summarise it.

      # Brings in the top-level `web` toolset on top of the parent's tools.
      - name: research
        description: Research a topic using web fetches in an isolated context.
        context: fork
        toolsets:
          - web
        instructions: Research the requested topic and summarise with links.

SKILL.md 파일에서의 동등한 것은 frontmatter 목록을 사용해요:

---
name: research
description: Research a topic using web fetches
context: fork
allowed-tools:
  - fetch
toolsets:
  - web
---

Note Fork 전용 두 필드 모두 비-fork 스킬에 설정되면 구성 검증이 거부하고, 최상위 toolset으로 해석되지 않는 toolsets 항목은 로드 타임 에러예요.

검색 경로 (Search Paths)

스킬은 다음 위치에서 발견돼요(나중 것이 이전 것을 재정의):

전역 (Global)

Path Search Type
~/.codex/skills/ 재귀 (모든 하위 디렉터리 검색)
~/.claude/skills/ 평면 (직접 자식만)
~/.agents/skills/ 재귀 (모든 하위 디렉터리 검색)

프로젝트 (git 루트에서 현재 디렉터리까지) — Project

Path Search Type
.claude/skills/ 평면 (cwd만)
.github/skills/ 평면 (git 루트에서 cwd까지 각 디렉터리)
.agents/skills/ 평면 (git 루트에서 cwd까지 각 디렉터리)

스킬 호출 (Invoking Skills)

스킬은 여러 방식으로 호출할 수 있어요:

  • 자동: 에이전트가 요청이 스킬의 설명과 일치함을 감지하고 자동으로 로드
  • 명시적: 프롬프트에서 스킬 이름 참조: "Use the create-dockerfile skill to..."
  • 슬래시 명령: /{skill-name} 로 스킬 직접 호출
# In the TUI, invoke skill directly:
/create-dockerfile

# Or mention it in your message:
"Create a dockerfile for my Python app (use the create-dockerfile skill)"

우선순위 (Precedence)

여러 스킬이 같은 이름을 공유할 때:

  • 전역 스킬이 먼저 로드
  • 프로젝트 스킬이 다음에, git 루트에서 현재 디렉터리 방향으로 로드
  • 현재 디렉터리에 더 가까운 스킬이 더 먼 것 재정의
  • 같은 디렉터리 레벨에서 .agents/skills/ 가 .github/skills/ 재정의

샌드박스 모드의 스킬 (Skills in Sandbox Mode)

--sandbox 로 에이전트를 실행하면 샌드박스 VM에 호스트의 스킬 디렉터리에 대한 접근이 없는 자체 파일시스템이 있어요. Docker Agent는 auto-kit 을 통해 이것을 투명하게 처리해요: 발견된 모든 로컬 스킬이 호스트의 에이전트별 kit 안으로 스테이징되고, best-effort 시크릿 지우기(auto-kit 문서 참고)를 통과하며, 읽기 전용으로 샌드박스에 바인드 마운트되어 호스트와 같은 스킬을 VM 안에서 에이전트가 보게 해요. 구성이 필요 없어요 — 호스트 스킬 없이 샌드박스를 명시적으로 실행하려는 경우에만 --no-kit 을 사용하세요.

스킬 만들기 (Creating a Skill)

# Create the skill directory
$ mkdir -p ~/.agents/skills/create-dockerfile

# Write the SKILL.md file
$ cat > ~/.agents/skills/create-dockerfile/SKILL.md << 'EOF'
---
name: create-dockerfile
description: Create optimized Dockerfiles for applications
---

# Creating Dockerfiles

When asked to create a Dockerfile:

1. Analyze the application type and language
2. Use multi-stage builds for compiled languages
3. Use slim base images to minimize size
4. Run as non-root user for security
EOF

스킬은 스킬이 활성화된(skills: true, 또는 그 이름을 대상으로 하는 목록 — Filtering Skills 참고) 모든 에이전트에 자동으로 사용 가능해져요.

Note 참고 (See also) 스킬은 Agent Config에서 skills 속성(불리언 또는 목록)으로 활성화돼요. 도구 기반 능력은 Tools 참고. 예제 구성: examples/skills_inline.yaml (인라인 스킬 정의), examples/skills_fork_toolsets.yaml (fork 스킬의 도구 범위 지정), examples/skills_filter.yaml (로드할 스킬 필터링).

더 알아보기 (Learn more)