Skip to main content
Skip to content

사용자 지정 기술

스킬은 Copilot의 기능을 확장하는 재사용 가능한 프롬프트 모듈입니다. 디렉터리에서 기술을 로드하여 특정 도메인 또는 워크플로에 대해 Copilot 특수한 기능을 제공합니다.

Overview

스킬은 Copilot에 지침을 제공하는 Markdown 문서인 SKILL.md 파일을 포함하는 이름이 지정된 디렉터리입니다. 로드되면 기술의 콘텐츠가 세션 컨텍스트에 삽입됩니다.

기술을 통해 다음을 수행할 수 있습니다.

  • 재사용 가능한 모듈로 도메인 전문 지식 패키지
  • 프로젝트 간에 특수한 동작 공유
  • 복잡한 에이전트 구성 정리
  • 세션당 기능 사용/사용 안 함

기술 불러오기

세션을 만들 때 기술을 포함하는 디렉터리를 지정합니다.

코드 언어 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5.4",
    skillDirectories: [
        "./skills/code-review",
        "./skills/documentation",
    ],
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

// Copilot now has access to skills in those directories
await session.sendAndWait({ prompt: "Review this code for security issues" });

기능 비활성화

다른 사람을 활성 상태로 유지하면서 특정 기술을 사용하지 않도록 설정합니다.

코드 언어 navigation

TypeScript
const session = await client.createSession({
    skillDirectories: ["./skills"],
    disabledSkills: ["experimental-feature", "deprecated-tool"],
});

기술 디렉터리 구조

각 기술은 파일을 포함하는 명명된 하위 디렉터리입니다.SKILL.md

skills/
├── code-review/
│   └── SKILL.md
└── documentation/
    └── SKILL.md

이 skillDirectories 옵션은 부모 디렉터리(예: ./skills)를 가리킵니다. CLI는 즉시 하위 디렉터리의 모든 SKILL.md 파일을 검색합니다.

SKILL.md 형식

SKILL.md 파일은 선택적 YAML 프런트매터가 있는 markdown 문서입니다.

---
name: code-review
description: Specialized code review capabilities
---

# Code Review Guidelines

When reviewing code, always check for:

1. **Security vulnerabilities** - SQL injection, XSS, etc.
2. **Performance issues** - N+1 queries, memory leaks
3. **Code style** - Consistent formatting, naming conventions
4. **Test coverage** - Are critical paths tested?

Provide specific line-number references and suggested fixes.

프런트매터 필드:

  • name: 기술의 식별자입니다(disabledSkills와 함께 사용하여 이를 선택적으로 비활성화하는 데 사용됨). 생략하면 디렉터리 이름이 사용됩니다.
  • description: 기술이 수행하는 일에 대한 간단한 설명입니다.

markdown 본문에는 기술이 로드될 때 세션 컨텍스트에 삽입되는 지침이 포함되어 있습니다.

스킬 제공업체(실험적)

참고

스킬 제공자는 실험적입니다. API는 향후 SDK 릴리스에서 변경될 수 있습니다.

스킬 공급자는 디스크의 SKILL.md 파일 대신 다중 테넌트 서비스의 데이터베이스와 같은 애플리케이션 자체 스토리지에서 스킬을 제공합니다. 공급자 기술은 파일 기반 기술과 함께 세션의 기술 카탈로그에 추가됩니다. 모델은 필요할 때 skill 도구를 통해 로드하고 사용자는 다른 기술처럼 호출할 수 있습니다.

공급자는 다음 두 가지 작업을 구현합니다.

  • 스킬 목록: 모든 스킬에 대한 카탈로그 메타데이터를 반환합니다. name, description, 선택적으로 userInvocable, disableModelInvocation 및 argumentHint. 런타임은 세션의 기술을 로드할 때 이를 호출합니다.
  • 스킬 읽기: 한 스킬에 대한 마크다운을 반환하거나, 스킬이 더 이상 존재하지 않는 경우 찾을 수 없는 결과를 반환합니다. 런타임은 기술이 로드될 때만 그것을 호출합니다.

세션을 만들거나 다시 시작할 때 provider를 전달하세요.

코드 언어 navigation

TypeScript
import { approveAll, CopilotClient, type SkillProvider } from "@github/copilot-sdk";

const releaseSkills = new Map([
    [
        "release-notes",
        {
            description: "Writes release notes in the team's format.",
            markdown: "Group changes by feature area and link each pull request.",
        },
    ],
]);

const skillProvider: SkillProvider = {
    listSkills: () =>
        [...releaseSkills].map(([name, skill]) => ({ name, description: skill.description })),
    readSkill: (name) => releaseSkills.get(name)?.markdown ?? null,
};

const client = new CopilotClient();
const session = await client.createSession({
    onPermissionRequest: approveAll,
    skillProvider,
});

Provider 스킬 콘텐츠

Read 스킬은 스킬의 SKILL.md 텍스트를 반환합니다. YAML 프런트매터는 선택 사항입니다.

  • frontmatter가 없으면 전체 텍스트가 스킬 본문이며 모든 메타데이터는 목록에 있는 스킬에서 가져옵니다.
  • 프런트매터를 사용하면 생략된 필드가 나열된 값을 상속합니다. 포함하는 필드는 나열된 값과 일치해야 합니다. 그렇지 않으면 스킬이 로드되지 않습니다.
  • allowed-tools 는 프런트매터에서만 읽습니다.
  • 텍스트의 첫 번째 줄이 ---면 런타임은 이를 프런트매터로 구문 분석하므로 Markdown 구분선을 사용하여 본문 전용 스킬을 시작하지 마세요.

기본적으로 provider 스킬은 텍스트 전용입니다. 기본 디렉터리가 없으므로 번들된 스크립트, 템플릿 또는 기타 파일을 참조할 수 없습니다. 이러한 파일을 공급자 스킬에 제공하려면 지원 파일을 참조하세요. skills.list는 소스 sdk 및 빈 path와 함께, 지원 파일의 유무와 관계없이 공급자 역량을 보고합니다.

지원 파일(실험적)

공급자 기술은 파일 기반 기술의 폴더와 동일한 방식으로 스크립트, 참조, 템플릿 및 자산과 같은 지원 파일과 함께 제공 될 수 있습니다. 애플리케이션은 각 스킬의 파일을 제어하는 폴더에 보관하고 나열된 스킬에서 directory를 해당 폴더의 절대 경로로 설정합니다.

모델이 기술을 활성화하면 런타임은 파일 기반 기술의 폴더를 나열하는 것과 동일한 방식으로 폴더를 나열합니다. 모델은 텍스트 전용 알림 대신 파일 기반 기술이 제공받는 동일한 "이 기술에 대한 기본 디렉터리" 줄 및 관련 파일 목록을 제공받고 일반 파일 도구로 파일을 읽습니다. 런타임은 파일 자체를 읽거나 복사하거나 쓰지 않습니다.

import { approveAll, CopilotClient, type SkillProvider } from "@github/copilot-sdk";

const skillProvider: SkillProvider = {
    listSkills: () => [
        {
            name: "release-notes",
            description: "Writes release notes in the team's format.",
            directory: "/srv/skills/release-notes",
        },
    ],
    readSkill: (name) =>
        name === "release-notes"
            ? "Run `python3 scripts/changelog.py` and fill in `templates/notes.md`."
            : null,
};

const client = new CopilotClient();
const session = await client.createSession({
    onPermissionRequest: approveAll,
    skillProvider,
});

각 SDK는 listed-skill 형식에서 폴더를 설정합니다.

SDKField
Node.jsdirectory: "/srv/skills/release-notes"
Pythondirectory="/srv/skills/release-notes"
GoDirectory: copilot.String("/srv/skills/release-notes")
.NETDirectory = "/srv/skills/release-notes"
Java여섯 번째 SkillProviderDescriptor 생성자 인수
러스트directory: Some("/srv/skills/release-notes".into())

폴더의 위치

각 기술마다 하나의 폴더를 두고, 해당 기술의 모든 파일을 그 directory 아래에 배치합니다. 폴더는 런타임이 실행되는 위치에서 액세스할 수 있어야 합니다.

  • 로컬 디스크. 세션 파일 시스템이 없으면 directory는 런타임을 실행하는 컴퓨터 또는 컨테이너의 경로입니다. 모델은 어떤 파일 도구로도 파일을 읽을 수 있으며 스크립트를 실행할 수 있습니다.
  • 세션 파일 시스템(다중 테넌트 및 서버 배포). sessionFs 처리기를 사용하면 directory 처리기의 경로 규칙을 사용하며, 처리기가 파일을 제공합니다. 런타임은 이를 통해 폴더를 나열합니다. view, create, edit 및 apply_patch 파일에 도달합니다. grep, glob, 셸 명령은 작동하지 않으므로 스크립트를 실행할 수 없습니다. Java SDK에는 sessionFs가 없습니다. 따라서 Java 공급자는 로컬 디스크를 사용합니다.

런타임은 읽기 기술이 반환된 후 폴더 내용을 나열하므로 읽기 기술에서 폴더를 지연해서 만들 수 있습니다. 폴더가 없거나 비어 있거나, 런타임이 read skill을 호출한 후 15초 이내에 나열할 수 없는 경우에도 모델은 파일 기반 기술에서와 같이 관련 파일 목록 없이 기본 디렉터리 줄을 계속 받습니다. 런타임이 기술을 나열할 때 sessionFs 처리기의 연결이 끊어진 경우 해당 기술은 다음 목록까지 텍스트 전용입니다.

Access

  • 로컬 디스크. 기술이 나열되면 런타임은 활성화된 각 공급자 기술의 skillDirectories를 구성된 directory 폴더처럼 처리합니다. 그 아래에서의 읽기 작업은 외부 작업 영역 경로 프롬프트를 건너뛰고, 샌드박스 처리된 프로세스는 이에 대한 읽기 전용 액세스 권한을 얻습니다. 읽기는 파일 기반 스킬에서와 마찬가지로 사용 권한 처리기로 계속 이동합니다. 홈 폴더 또는 모든 테넌트의 파일을 보유하는 폴더와 같은 광범위한 디렉터리를 지정하지 마세요.
  • 세션 파일 시스템입니다. 런타임은 폴더에 대한 액세스 권한을 추가하지 않습니다. 사용 권한 처리기에서 그 아래의 항목에 대한 읽기를 승인하도록 하고 샌드박스가 켜지면 폴더를 샌드박스의 readonlyPaths에 추가합니다.

애플리케이션이 폴더를 관리합니다. 즉, 폴더의 위치, 존재 기간, 정리, 그리고 모델이 이를 변경하지 못하게 하는 것을 책임집니다. 읽기 전용 액세스는 샌드박스 처리된 프로세스만 포함합니다. 샌드박스 외부 또는 폴더가 작업 영역 내에 있는 경우 사용 권한 처리기 또는 sessionFs 처리기가 거부하지 않는 한 모델은 해당 폴더에 쓸 수 있습니다.

스킬 작성

  • 관련 파일은 skill의 폴더를 기준으로 한 상대 경로(예: references/guide.md)로 참조하세요. 모델에 폴더의 절대 경로가 전달됩니다.
  • 스킬에서 스크립트 사용에 설명된 대로, python3 scripts/changelog.py 또는 bash scripts/build.sh와 같은 인터프리터를 통해 스크립트를 실행합니다. 스크립트는 폴더가 로컬 디스크에 있는 경우에만 실행됩니다.

규칙 및 제한

  • directory는 세션의 경로 규칙에서 절대 경로여야 합니다. Windows 스타일 세션 파일 시스템에서는 드라이브 문자 또는 UNC 접두사가 필요합니다. 파일 도구가 경로를 해석하는 방식으로 해석되므로 . 및 .. 세그먼트와 반복되거나 후행하는 구분 기호가 제거되며, 파일 시스템 루트로 해석될 수 없습니다. 카탈로그의 1MiB 메타데이터 제한에 포함되며 기술 카탈로그에는 표시되지 않습니다. 잘못된 directory 항목은 나열된 다른 잘못된 기술과 마찬가지로 전체 카탈로그가 거부되게 합니다.
  • 관련 파일 목록은 파일 기반 규칙을 따릅니다. node_modules, dist, bin, obj와 같은 빌드 및 종속성 폴더는 숨겨지고, 50개가 넘는 항목이 있는 폴더는 요약되며, 10개를 초과하는 폴더 깊이에 중첩된 파일은 나열되지 않고, SKILL.md는 절대 나열되지 않으며, 표시되는 파일 수는 최대 100개입니다.
  • 대화가 압축된 후 모델은 스킬의 지침을 유지하지만 폴더 경로는 유지하지 않습니다. 스킬을 다시 호출하면 표시됩니다. 파일 기반 스킬은 경로를 유지합니다.
  • 지원 파일에는 해당 파일을 추가한 SDK 릴리스와 같거나 그보다 최신 버전의 Copilot CLI가 필요합니다. 나열된 기술 중 하나에 directory가 있으면 이전 CLI는 전체 기술 카탈로그를 거부합니다. directory를 설정하지 않은 공급자는 이전 CLI에서 작동합니다.

기존 SKILL.md 파일 처리

데이터베이스에 저장된 파일과 같이 이미 있는 SKILL.md 파일을 제공하려면 각 파일의 YAML 프런트매터를 한 번 구문 분석하여 카탈로그 항목을 빌드한 다음 read 스킬에서 변경되지 않은 파일을 반환합니다.

  • name 및 description을 나열된 기술의 name 및 description에 매핑합니다. 카탈로그에는 둘 다 필요합니다. 런타임은 폴더 이름 또는 스킬 본문을 기본값으로 사용하지 않습니다.
  • 프런트매터에서 disable-model-invocation, argument-hint, user-invocable를 설정하면 일치하는 선택적 필드에 매핑합니다.
  • read skill에서 프런트매터를 포함한 원래 텍스트를 반환합니다. 나열된 값은 동일한 프런트매터에서 제공되었으므로 일치하며 런타임은 여전히 여기에서 allowed-tools를 읽습니다.

공급자 콘텐츠를 신뢰함

제공자 스킬을 스킬 디렉터리처럼 처리합니다. 콘텐츠는 신뢰되는 입력 데이터입니다. 모델은 스킬의 지침을 따르고, 프런트매터는 스킬이 호출되는 방식을 제어합니다. allowed-tools 는 SDK 세션에서 권한을 부여하지 않습니다. 런타임은 이를 allowedTools 이벤트의 skill.invoked 필드에 보고하고, 권한 처리기는 여전히 모든 도구 요청을 결정합니다.

최종 사용자 또는 다른 테넌트가 스킬 파일을 작성하도록 허용하지 않는 한 편집할 수 있는 텍스트를 표시하지 마세요. 사용자 입력에서 스킬을 빌드하는 경우 사용자가 제공한 프런트매터를 전달하는 대신 직접 프런트매터를 생성합니다.

공급자 제한 및 오류

런타임은 공급자의 카탈로그 및 콘텐츠의 유효성을 검사합니다.

  • 이름은 ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$와 일치해야 하며, 대/소문자를 무시하고 고유해야 합니다.

  • 카탈로그에는 최대 1,024개의 기술과 1MiB의 메타데이터가 포함될 수 있습니다. 각 설명 및 인수 힌트는 최대 1,024자일 수 있습니다.

  • 각 기술의 마크다운은 UTF-8 기준 최대 1MiB까지 가능합니다.

  • 각 호출은 30초 이내에 완료되어야 합니다. 런타임이 시간 초과, 세션 종료 또는 공급자 교체로 인해 호출 대기를 중지하면 요청을 취소하고 이후 결과를 무시합니다. 각 SDK는 일반적인 방법으로 해당 취소를 제공업체에 전달합니다.

    SDK취소 신호
    Node.js

readSkill 및 AbortSignal에 전달된 옵션의 signal(listSkills)이 중단됩니다. | | Python | 공급자의 asyncio 작업이 asyncio.CancelledError와 함께 취소됩니다. 동기 공급자는 완료될 때까지 실행됩니다. | | Go | 통화의 context.Context이(가) 취소되었습니다. | | .NET | CancellationToken 통화의 취소되었습니다. | | Java | CompletableFuture에서 반환된 작업은 실행 중인 작업을 중단하지 않는 cancel(true)로 취소됩니다. | | 러스트 | 공급자 퓨처는 삭제됩니다. |

이러한 신호는 런타임이 취소하는 호출을 다룹니다. 연결이 닫히거나 클라이언트가 강제로 중지되면 .NET, Java 및 Rust SDK도 여전히 실행 중인 호출을 취소합니다. Node.js, Python 및 Go SDK는 그렇지 않습니다: 실행 중인 호출은 반환될 때까지 계속되며, SDK는 그 결과를 삭제합니다.

목록화에 실패하거나 잘못된 카탈로그를 반환하는 경우 런타임은 errors에서 반환된 skills.reload 목록에 문제를 보고합니다. 다시 로드에 실패하면 가장 최근에 성공적으로 로드된 목록의 provider 스킬이 유지됩니다. 스킬을 읽는 데 실패하면 skill 도구는 모델에 일반적인 로드 실패를 보고합니다. SDK는 프로바이더가 throw하거나 반환하는 오류 텍스트를 전달하지 않으므로 해당 텍스트가 대화에 누출될 수 없습니다.

공급자 수명 주기

공급자는 한 세션에 바인딩됩니다.

  • 공급자는 enableSkills를 false로 설정하지 않는 한 기술을 사용하도록 설정하며, 이렇게 설정하면 공급자는 바인딩된 상태로 유지되지만 호출되지는 않습니다. mode: "empty"에서는 enableSkills을(를) true(으)로 설정할 때까지 기술이 비활성화됩니다.
  • 공급자는 저장되지 않습니다. 세션을 다시 시작할 때 다시 전달하세요. 공급자 없이 다시 열면 해당 항목이 세션에서 제거됩니다. 세션에 참가하는 확장은 세션을 변경하지 않습니다.
  • 파일 기반 기술과 이름이 같은 공급자 기술이 파일 기반 기술을 대체하고 skills.reload에서 경고를 표시합니다.
  • 하위 에이전트는 부모 세션의 프로바이더를 사용합니다.
  • 런타임은 skill 도구, 사용자 호출 및 스킬을 미리 로드하는 사용자 지정 에이전트에서 공급자를 동시에 호출할 수 있으므로 두 작업 모두 동시에 사용하기에 안전해야 합니다.
  • 클라우드 세션은 스킬 공급자를 지원하지 않습니다. SDK는 세션을 만들기 전에 구성을 거부합니다.

구성 옵션

SessionConfig 기술 필드

언어FieldTypeDescription
Node.jsskillDirectoriesstring[]기술을 로드하기 위한 디렉터리
Node.jsdisabledSkillsstring[]사용하지 않도록 설정하는 기술
Node.jsskillProviderSkillProviderSDK 제공 스킬에 대한 실험적 공급자
Pythonskill_directorieslist[str]기술을 로드하기 위한 디렉터리
Pythondisabled_skillslist[str]사용하지 않도록 설정하는 기술
Pythonskill_providerSkillProviderSDK 제공 스킬에 대한 실험적 공급자
GoSkillDirectories[]string기술을 로드하기 위한 디렉터리
GoDisabledSkills[]string사용하지 않도록 설정하는 기술
GoSkillProviderSkillProviderSDK 제공 스킬에 대한 실험적 프로바이더
.NETSkillDirectoriesList<string>기술을 로드하기 위한 디렉터리
.NETDisabledSkillsList<string>사용하지 않도록 설정하는 기술
.NETSkillProviderISkillProviderSDK 제공 스킬에 대한 실험적 공급자
JavasetSkillProviderSkillProviderSDK 제공 스킬에 대한 실험적 공급자
러스트with_skill_providerArc<dyn SkillProvider>SDK 제공 스킬에 대한 실험적 프로바이더

기본 제공 기술 및 mode: "empty"

런타임에는 기본적으로 사용할 수 있는 함께 제공되는 내장 스킬 세트가 포함되어 있습니다. 에서 클라이언트를 실행하면(mode: "empty"에 권장되는 기준 환경), SDK는 런타임 번들에 포함된 모든 기본 제공 스킬을 제외합니다. 그리고 빈 installedPlugins 목록과 함께 post-create 및 post-resume 옵션 패치에서 빈 includedBuiltinSkills 목록을 전송합니다.

이 제외는 영구 제한이 아닌 기본값입니다. 선택한 런타임 번들 스킬을 허용하려면 includedBuiltinSkills를 해당 이름(또는 언어별 대/소문자 표기)으로 설정합니다. mode: "empty"에서 자체 사용자 지정 스킬을 선택적으로 활성화할 수도 있습니다. 스킬을 활성화하고 자체 skillDirectories를 전달하면 기본 제공 스킬과 이름이 같은 사용자 지정 스킬을 포함하여 해당 스킬을 모두 사용할 수 있습니다. 옵션을 설정하지 않으면 필드 아래에 mode: "copilot-cli" 생략됩니다.

사용자 지정 기술 디렉터리(해당 시점에 누락되거나 비어 있는 디렉터리를 포함하여)는 기술이 처음 로드될 때 검색됩니다. 이러한 디렉터리의 파일 시스템 변경은 이후 차례에 카탈로그를 자동으로 새로 고치지 않습니다. 기술을 추가, 편집 또는 제거한 후 세션의 skills.reload RPC를 호출합니다.

SDK호출 다시 불러오기
Node.jsawait session.rpc.skills.reload()
Pythonawait session.rpc.skills.reload()
Gosession.RPC.Skills.Reload(ctx)
.NETawait session.Rpc.Skills.ReloadAsync()
Javasession.getRpc().skills.reload().join()
러스트session.rpc().skills().reload().await?

구성된 스킬 디렉터리를 변경하면 카탈로그도 새로 고쳐집니다.

모범 사례

  1. 도메인별로 구성 - 관련 기술 그룹화(예: skills/security/, skills/testing/)

  2. 프런트매터 사용 - 명확성을 위해 YAML 프런트매터 포함 name 및 description 포함

  3. 문서 종속성 - 기술에 필요한 도구 또는 MCP 서버에 유의하세요.

  4. 격리된 기술 테스트 - 기술을 결합하기 전에 기술 작동 확인

  5. 상대 경로 사용 - 환경에서 기술을 이식 가능한 상태로 유지

다른 기능과 결합

기술 + 사용자 지정 에이전트

에이전트 skills 필드에 나열된 기술은 즉시 미리 로드됩니다. 시작 시 에이전트의 컨텍스트에 전체 콘텐츠가 삽입되므로 에이전트는 기술 도구를 호출할 필요 없이 즉시 기술 지침에 액세스할 수 있습니다. 스킬 이름은 세션 수준의 skillDirectories에서 조회됩니다.

const session = await client.createSession({
    skillDirectories: ["./skills/security"],
    customAgents: [{
        name: "security-auditor",
        description: "Security-focused code reviewer",
        prompt: "Focus on OWASP Top 10 vulnerabilities",
        skills: ["security-scan", "dependency-check"],
    }],
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

참고

스킬은 옵트인 방식이므로 skills가 생략되면 스킬 콘텐츠가 주입되지 않습니다. 하위 에이전트는 부모로부터 기술을 상속하지 않습니다. 에이전트별로 명시적으로 나열해야 합니다.

기술 + MCP 서버

기술은 MCP 서버 기능을 보완할 수 있습니다.

const session = await client.createSession({
    skillDirectories: ["./skills/database"],
    mcpServers: {
        postgres: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-postgres"],
            tools: ["*"],
        },
    },
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

Troubleshooting

기술이 로드되지 않음

  1. 경로 확인 - 기술 디렉터리 경로가 올바르고 파일이 있는 하위 디렉터리가 SKILL.md 포함되어 있는지 확인합니다.
  2. 권한 확인 - SDK가 디렉터리를 읽을 수 있는지 확인
  3. SKILL.md 형식 확인 - markdown이 올바른 형식이고 YAML 프런트매터가 유효한 구문을 사용하는지 확인합니다.
  4. 디버그 로깅 활성화 - 스킬 로딩 로그를 보려면 logLevel: "debug"으로 설정

기술 충돌

여러 기술이 충돌하는 지침을 제공하는 경우:

  • disabledSkills를 사용하여 충돌하는 기술을 제외하십시오.
  • 겹치지 않도록 기술 디렉터리 다시 구성

참고하십시오