Copilot Cowork용 플러그인 만들기

적용 대상: Microsoft Copilot

Microsoft Copilot Cowork는 Teams 앱, Copilot 에이전트 및 Office 추가 기능에 사용되는 것과 동일한 배포 메커니즘인 M365 앱 패키지를 통해 확장성을 지원합니다. 다음을 사용하여 Cowork를 확장할 수 있습니다.

스킬: 재무 분석, 법률 연구 또는 HR 워크플로와 같은 새로운 도메인 전문 지식을 Cowork에 가르치는 프롬프트 기반 워크플로입니다.
커넥터: Cowork가 외부 데이터 원본 및 API에 액세스할 수 있도록 하는 원격 서버입니다.

둘 다 표준 Microsoft 365 앱 패키지에 함께 패키지되어 Microsoft 365 App Store를 통해 배포됩니다.

Important

Microsoft Purview 정보 장벽 (IB)는 현재 플러그 인 또는 스킬 관리 및 공유를 지원하지 않습니다. IB가 활성화된 테넌트에서는 임베디드 지식 파일 업로드가 테넌트 수준에서 차단됩니다. 이렇게 하면 영향을 받는 플러그인과 스킬이 업로드되거나 게시되지 않습니다.

Microsoft는 크롤링, 스크래핑, 수집, 대량 내보내기, 수집 또는 기타 방법(API, MCP 서버 또는 기타)을 통해 ISV 콘텐츠를 포함하는 영구 인덱스, 지식 그래프(Microsoft Graph 포함) 또는 데이터베이스를 만들거나 유지 관리하지 않습니다. Microsoft 사용자의 실시간 쿼리에 응답하기 위해 필요에 따라 ISV 콘텐츠를 일시적으로 처리할 수 있지만 해당 세션 기간 이후의 ISV 콘텐츠는 유지되지 않습니다. ISV의 서면 요청이 있는 경우 Microsoft는 영업일 기준 10일 이내에 소유 또는 관리 중인 모든 ISV 콘텐츠를 삭제하고 서면으로 이를 인증합니다. Microsoft Copilot 및 Microsoft Copilot Chat의 엔터프라이즈 데이터 보호에 대해 자세히 알아보세요.

빌드할 내용

Cowork 플러그인은 다음을 포함하는 .zip 패키지입니다.

my-extension.zip
├── manifest.json          # M365 Unified App Manifest (v1.28)
├── color.png              # 192×192 full-color app icon
├── outline.png            # 32×32 outline icon
└── skills/                # Agent Skills (SKILL.md files)
    ├── skill-one/
    │   ├── SKILL.md
    │   └── references/    # Optional deep-dive docs
    └── skill-two/
        └── SKILL.md

스킬은 Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie 및 30개 이상의 기타 AI 도구에서도 지원하는 동일한 형식의 Agent Skills 오픈 표준을 사용합니다.

시작점 선택

wiqd CLI를 사용하여 플러그인을 빌드하세요. CLI는 패키지를 스캐폴딩하고 manifest.json와 사용자의 기술 폴더를 동기화된 상태로 유지합니다. 또한 업로드하기 전에 플랫폼의 자체 유효성 검사 규칙을 실행한 다음 결과를 프로비전하고 공유합니다. CLI는 미리 보기 상태이므로 일반 공급 전에 해당 명령과 생성된 출력이 변경될 수 있습니다. 생성되는 모든 항목은 일반 Microsoft 365 앱 패키지이므로 파일을 직접 열고, 편집하고, 파일의 버전을 관리할 수 있습니다.

도구를 설치할 수 없거나 자체 패키징 파이프라인을 구축하는 경우에만 패키지를 수동으로 만드세요. 그 경우에는 이 문서의 패키지 형식 참조가 필요합니다. 이는 wiqd가 정확히 무엇을 생성하는지 설명합니다.

출발점	이것을 하세요	첫 패키지까지 소요 시간
처음부터 시작합니다.	wiqd를 사용하여 플러그인 빌드하기	약 10분
기존 Claude 코드 플러그인이 있습니다	변환하기	약 5분
도구를 설치할 수 없거나 자체 패키징을 스크립팅하고 있습니다	패키지를 수동으로 구성	약 30분

wiqd로 플러그인 만들기

wiqd CLI는 사용자가 달리 수동으로 수행하는 것과 동일한 수명 주기(생성, 기능 추가, 유효성 검사, 프로비저닝, 패키징 및 공유)를 실행합니다. 이 패키지가 생성하는 패키지는 이미 이 문서의 유효성 검사 규칙을 충족합니다.

Windows, macOS 및 Linux를 다루는 wiqd 설치 가이드에 따라 wiqd CLI를 설치합니다. 그런 다음 개발 중인 Microsoft 365 테넌트에 로그인합니다. 프로비전과 공유는 모두 테넌트와 상호 작용하기 때문입니다.

wiqd auth login --interactive

또한 설치 프로그램은 GitHub Copilot CLI 플러그인을 등록하므로 동일한 수명 주기를 대화형으로 수행할 수 있습니다. 예를 들어, Triage Helper라는 독립 실행형 플러그인 만들기 또는 내 플러그인의 유효성을 검사해 줘.라고 말할 수 있습니다. 대화형 경로는 이 섹션과 동일한 명령을 실행합니다. 파이프라인을 스크립팅하거나 재현 가능한 비대화형 자동화를 원하는 경우 명령을 직접 사용하세요.

2단계: 플러그인을 구성하고 기능 추가

플러그인 컨테이너를 만든 다음, 필요한 기능을 원하는 대로 조합하여 추가하세요.

wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp

add skill로 appPackage/skills/contract-analysis/SKILL.md를 스캐폴드하고 agentSkills[]에 등록합니다. add connector 은 agentConnectors[] 항목을 씁니다. 두 명령 모두 기록하기 전에 플랫폼의 명명 규칙과 크기 제한을 적용하므로 폴더 이름 불일치나 길이 제한을 초과한 id는 매니페스트에 기록되지 않습니다.

생성된 SKILL.md에 스킬 로직을 작성하세요. 프런트매터 필드, 프로그레시브 로딩 모델, 그리고 컴패니언 파일 제한은 1단계: 첫 번째 스킬 만들기 및 2단계: 참조 자료 추가(선택 사항)에 설명된 내용과 동일합니다.

Important

wiqd plugin create는 패키지를 manifestVersion: "1.29"에 고정하는 반면, 이 문서의 수작업으로 작성된 예제에서는 1.28를 사용합니다. 이 차이는 커넥터에서 중요합니다. 1.28에는 mcpToolDescription이 필요하며, 여기서 지정하는 파일이 ZIP에 있어야 합니다. 1.29 버전에서는 agentConnectors[] 항목에 URL만 지정하면 되며 mcpToolDescription은 선택 사항이므로, wiqd로 생성한 패키지에서 해당 업로드 오류가 발생하지 않습니다. WIQD는 커넥터 인증을 아직 스캐폴딩하지 않습니다. 지원되는 인증 유형에 설명된 대로 직접 구성합니다.

3단계: 구성하면서 유효성 검사

패키지를 구성한 뒤 업로드가 성공하기를 바라는 대신, 지속적으로 검증을 수행하세요.

wiqd plugin validate
wiqd plugin validate --mode deep

validate 는 선언적 에이전트 영역에 대한 오프라인 정적 검사입니다. 기술 전용 또는 커넥터 전용 플러그인은 의도된 대로 별도의 검사 과정 없이 이를 통과시킵니다. 전체 커버리지가 아닌, 빌드 루프에 대한 검사이기 때문입니다. validate --mode deep 먼저 플러그 인을 패키지한 다음 업로드에서 사용하는 동일한 앱 유효성 검사 라이브러리에 대해 빌드된 .zip 항목의 유효성을 검사합니다. 바로 여기서 ASKILL 코드 및 커넥터 규칙이 등장합니다.

다음 세 가지 명령을 순서대로 실행합니다.

wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com

package 및 share 단계가 공통으로 의존하는 환경 파일을 작성하므로, 반드시 provision을 먼저 실행하십시오. 목록에 있는 사용자와 공유하려면 --scope users를 사용하고, 조직 내 모든 사용자와 공유하려면 --scope tenant를 사용하세요. 어느 경우든 플러그인은 공유한 항목 아래의 Cowork>소스 및 기술>플러그인 아래에 나타납니다. 대신 관리자가 패키지를 업로드하여 검색 섹션에 나열합니다. 8단계: 테넌트에 게시에서 자세히 알아보세요. provision가 만든 항목을 제거하려면 wiqd plugin delete --env local --yes를 실행합니다.

퍼블릭 스토어 제출은 여전히 파트너 센터에서 수동으로 진행되는 프로세스입니다. 자세한 내용은 9단계: 대중에 게시를 참조하세요.

플러그인을 다른 호스트로 옮기기

Claude Code, Cursor 또는 기타 에이전트 기술 호스트에서 기술을 사용하려면 수동으로 폴더를 복사하는 대신 프로젝트를 내보내세요.

wiqd plugin export --format claude-plugin

의 기본값은 이며 도 허용합니다. <path>/export/<format> 아래에 압축되지 않은 디렉터리를 씁니다.

기존 플러그 인 가져오기

이미 기술과 MCP 서버가 포함된 Claude Code 플러그인이 있는 경우 두 가지 변환 경로가 있습니다. 선택하는 경로는 플러그인을 계속 개발할 계획인지 아니면 가지고 있는 것만 제공할 계획인지에 따라 다릅니다.

목표	사용
Microsoft 365용 플러그인을 계속 개발, 검증 및 배포하세요	`wiqd plugin import`
기존 Claude 플러그인에서 지금 바로 배포 가능한 `.zip` 파일 생성하기	변환 스크립트

wiqd를 사용하여 가져오기

wiqd plugin import 는 Open Plugin, Claude 플러그 인 또는 커서 플러그 인 소스를 인식하고 해당 플러그 인에서 wiqd 플러그 인 프로젝트를 생성합니다. 가져온 플러그인은 wiqd plugin create로 생성한 플러그인과 동일한 수명 주기를 따릅니다.

wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

--privacy-url 및 --terms-url는 플러그인의 첫 번째 가져오기에서만 필요합니다. 소스가 이전 wiqd plugin export에서 생성된 것이라면, 왕복 처리에 필요한 메타데이터가 이미 포함되어 있습니다.

Important

가져온 프로젝트에서는 수명 주기 중 읽기 전용 작업인 wiqd plugin validate, show, list만 지원합니다. 이는 가져오기가 해당 단계에 필요한 로컬 배포용 파일을 생성하지 않기 때문에 아직 패키징하거나, 프로비저닝하거나, 공유할 수 없습니다. 이는 추적되는 간격입니다. 현재 상태는 wiqd CLI 참조에서 확인하세요. 지금 게시 가능한 패키지가 필요한 경우 변환 스크립트를 사용하세요.

변환 스크립트를 사용하여 변환

변환 스크립트는 Claude 플러그인을 게시 가능한 M365 패키지로 직접 변환합니다.

CLI를 설치합니다(버전 1.1.12 이상 필요).
```
npm install -g @microsoft/m365agentstoolkit-cli
```
버전을 확인하세요:
```
atk --version
```

플러그인 가져오기:

atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

이 명령은 플러그인의 .claude-plugin/plugin.json(또는 .cursor-plugin/plugin.json), .mcp.json 및 skills/ 디렉터리를 읽은 다음, appPackage/manifest.json, 해당 기술 및 생성된 아이콘이 포함된 Agents Toolkit 프로젝트의 기본 구조를 생성합니다.

플러그인 매니페스트에는 해당하는 필드가 없고 Microsoft 365 매니페스트에는 두 필드가 모두 필요하기 때문에 --terms-url 및 --privacy-url를 포함해야 합니다.

비고

atk import openplugin는 .mcp.json와 함께 점 접두사 디렉터리(.claude-plugin/plugin.json, .cursor-plugin/plugin.json 또는 .plugin/plugin.json)에서 플러그인 매니페스트를 찾습니다. 에이전트 플러그인 1.0.0 사양은 매니페스트를 최상위 수준 plugin.json에 배치하고 MCP 구성을 mcp.json에 배치합니다. 1.0.0 레이아웃을 따르는 플러그인을 가져오려면 매니페스트를 .plugin/plugin.json로 이동하고 mcp.json의 이름을 .mcp.json로 바꾸세요.

결과를 업로드할 수 있는 .zip으로 패키지화합니다.

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

비고

atk import openplugin는 devPreview 매니페스트를 생성합니다. 이 문서의 다른 곳에 있는 매니페스트 예제는 스키마 v1.28을 대상으로 합니다. v1.28이 필요한 채널을 통해 게시하는 경우 생성된 appPackage/manifest.json에서 manifestVersion 및 $schema을 업데이트하세요.

가져올 항목

플러그인 아티팩트	M365 동등 항목	Notes
`.claude-plugin/plugin.json`	`manifest.json`	이름, 설명 및 개발자 필드가 매핑됨, GUID 자동 생성(결정적 UUID v5)
`skills/*/SKILL.md`	`agentSkills[]` entries + `skills/` folder	축어 복사 - 동일한 형식
`.mcp.json` 서버들	`agentConnectors[]` 항목	URL 및 인증 유형 자동 감지됨
`color.png` / `outline.png`	패키지의 아이콘	있으면 사용하고, 없으면 자리 표시자를 생성합니다.

Important

.mcp.json에서 가져온 각 커넥터에 대해 생성된 authorization.referenceId는 플러그인 및 서버 이름에서 파생된 자리 표시자입니다. 게시하기 전에 실제 OAuth 클라이언트 등록 ID로 바꿉니다. 지원되는 인증 유형에서 자세히 알아보세요.

변환되지 않는 항목

다음 Claude 플러그인 기능은 Microsoft 365 매니페스트에서 아직 지원되지 않습니다.

Claude 플러그인 기능	상태
`commands/` (슬래시 명령)	아직 지원되지 않음
`agents/` (하위 에이전트)	아직 지원되지 않음
`hooks/` (이벤트 처리기)	아직 지원되지 않음
`settings.json`	적용할 수 없음
`bin/` (실행 파일)	적용할 수 없음

가져오기 옵션

Option	Description
`--path`, `-p`	Required. `.cursor-plugin/plugin.json`, `.claude-plugin/plugin.json` 또는 `.plugin/plugin.json`를 포함하는 플러그인 디렉터리
`--output`, `-o`	대상 프로젝트 폴더(기본값: `./<plugin-name>`)
`--privacy-url`	`developer.privacyUrl` 생성된 매니페스트용
`--terms-url`	`developer.termsOfUseUrl` 생성된 매니페스트용
`--website-url`	`developer.websiteUrl`; `homepage`를 사용하고, 없으면 `author.url`을 사용합니다
`--app-id`	매니페스트 `id`에 대해 생성된 결정적 UUID v5를 재정의합니다
`--default-auth-type`	`Auto` (기본값), `None`, `OAuthPluginVault`또는 `ApiKeyPluginVault`

인증 유형 자동 검색:

Source	기본 인증 유형	Reason
외부 HTTPS URL	`OAuthPluginVault`	대부분의 원격 API에는 인증이 필요합니다.
`localhost` 및 HTTPS가 아닌 URL	`None`	로컬 개발 서버들

자동 검색이 설정과 일치하지 않으면 --default-auth-type를 사용하여 자동 감지를 재정의하세요.

플러그 인 디렉터리로 다시 내보내기

에이전트 툴킷 프로젝트를 플러그인 디렉터리로 다시 이동하려면(예: Claude 코드 플러그인과 Cowork 패키지를 동기화 상태로 유지) 다음을 사용합니다atk export openplugin.

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin

Option	Description
`--path`, `-p`	Required. 다음이 포함된 에이전트 도구 키트 프로젝트 폴더 `appPackage/manifest.json`
`--output`, `-o`	대상 플러그인 디렉터리(기본값: `./<plugin-name>-openplugin`)
`--manifest-kind`	`open-plugin` (기본값, `.plugin/plugin.json`에 기록함), `claude-plugin`, 또는 `cursor-plugin`

내보내기는 생성된 plugin.json에 x-microsoft-365-agents-toolkit 블록을 추가합니다. 이 블록은 매니페스트 id, 개발자 URL 및 커넥터 설정을 전달하므로 나중에 atk import openplugin이 다시 --privacy-url나 --terms-url가 필요 없이 왕복 처리될 수 있습니다.

비고

x-microsoft-365-agents-toolkit 이 블록은 Agents Toolkit에만 적용되며, 기본 open-plugin 종류는 매니페스트를 .plugin/plugin.json에 씁니다. 에이전트 플러그인 1.0.0은 최상위 수준에서 plugin.json를 사용하고 역방향 도메인 네임스페이스가 있는 extensions 키 아래에 클라이언트별 데이터를 담고 있으므로 다른 클라이언트는 이 블록을 처리하지 않고 이 블록을 무시합니다. 대상이 Claude Code 또는 Cursor인 경우 cursor-plugin 또는 --manifest-kind claude-plugin를 사용합니다.

레거시: PowerShell 변환 스크립트

atk에서 플러그인 가져오기를 지원하기 전에는 Windows 전용 PowerShell 스크립트를 사용하여 변환했으며, 이 스크립트는 여전히 다음 변환 스크립트 링크를 통해 사용할 수 있습니다.

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

atk import openplugin를 대신 사용하세요. 크로스 플랫폼을 지원하고 Cursor 및 Claude Code 소스를 지원하며 플러그인 디렉터리로 다시 내보낼 수 있습니다.

패키지를 수동으로 조립

이 섹션은 패키지 형식 참조 가이드입니다. wiqd로 플러그인 빌드하기에서 생성되는 결과물을 필드별로 정확하게 설명합니다. 도구를 설치할 수 없거나 자체 패키징 파이프라인을 빌드할 때 처음부터 끝까지 따라하세요. 생성된 패키지를 이해하거나 디버그해야 할 때 참고하세요.

1단계: 첫 번째 기술 만들기

스킬은 SKILL.md 파일이 포함된 폴더입니다. 다음 폴더 구조를 만듭니다.

my-extension/
└── skills/
    └── contract-analysis/
        └── SKILL.md

YAML 프런트매터와 Markdown 본문으로 SKILL.md을 작성하세요.

---
name: contract-analysis
description: |
  Analyzes contracts for key terms, risks, and obligations.
  Use when user asks to "review this contract", "find the liability clause",
  "summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
  author: Contoso Legal Tech
  version: "1.0"
---

# Contract Analysis

## What This Skill Does

Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions

## Workflow

1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations

## Output Format

Present findings in a structured table:

| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |

SKILL.md frontmatter 필드

필수 필드:

Field	Constraints	Description
`name`	1-64자, 케밥-케이스	기술 식별자 - 폴더 이름과 정확하게 일치해야 함
`description`	1-1024자	이 스킬을 사용해야 하는 경우 - 트리거 문구 포함

Important

폴더 이름은 프론트매터의 name 필드와 일치해야 합니다. 이러한 불일치는 스킬 실패의 가장 일반적인 원인입니다.
플러그인 목록 description 필드에는 사용자를 구독을 구매하기 위해 외부 마켓플레이스로 안내하는 행동 촉구가 포함되어서는 안 됩니다.

폴더 경로	`name` 필드	유효한가요?	이유
`skills/contract-analysis/SKILL.md`	`contract-analysis`	Yes	폴더와 이름이 일치합니다
`skills/contract-analysis/SKILL.md`	`ContractAnalysis`	No	이름이 폴더와 일치하는 대신 PascalCase를 사용합니다
`skills/my-skill/SKILL.md`	`contract-analysis`	No	폴더는 `my-skill`이지만 이름은 `contract-analysis`입니다

명명 규칙(kebab-case): 소문자 영숫자 및 하이픈만 사용합니다. 연속된 하이픈을 사용하지 말고, 선행 또는 후행 하이픈을 사용하지 마세요.

Example	유효한가요?	Issue
`bond-relative-value`	Yes	하이픈으로 연결된 소문자
`fx-carry-trade`	Yes	하이픈으로 연결된 소문자
`email`	Yes	단일 단어, 하이픈은 필요하지 않습니다
`Bond_Relative_Value`	No	밑줄과 대문자
`--my-skill--`	No	선행 및 후행 하이픈
`my--skill`	No	연속된 하이픈

2단계: 참조 자료 추가(선택 사항)

복잡한 기술의 경우 기본 SKILL.md를 간결하게 유지하고 세부 콘텐츠를 하위 디렉터리로 이동합니다. 이러한 추가 파일은 보조 파일입니다. 기술은 필요할 때 로드합니다.

skills/
└── contract-analysis/
    ├── SKILL.md               # Core workflow (~1,500-2,000 words ideal)
    ├── references/            # Deep-dive docs loaded on demand
    │   ├── clause-taxonomy.md
    │   └── risk-scoring.md
    └── scripts/               # Executable utilities
        └── extract-clauses.py

보조 파일 제한

각 기술에는 최대 20개의 동반 파일(SKILL.md 이외의 모든 파일)이 포함될 수 있습니다. 기술당 적용되는 제한 사항은 다음과 같습니다.

Limit	Value
최대 동반 파일 수	20
동반 파일당 최대 크기	5MB
최대 총 보조 크기	10MB
다운로드 시간 제한(모든 보조)	15초

보조 파일 규칙

컴패니언 파일 경로는 다음 규칙을 따라야 합니다.

상대 경로만 사용합니다(절대 경로는 사용하지 않음).
경로 통과(.. 세그먼트)가 없습니다.
파일 이름에 백슬래시 또는 null 바이트가 없습니다.
숨김 파일(.로 시작하는 이름)이 없습니다.
Windows 예약 이름(CON, PRN, AUX, NUL, COM1–COM9, LPT9–LPT1)은 사용할 수 없습니다.
파일 SKILL.md 자체는 보조 파일로 간주되지 않습니다.
파일 이름에는 영문자와 숫자, 하이픈, 밑줄, 마침표, 공백 및 !만 사용할 수 있습니다.

컨텍스트 창을 효율적으로 유지하기 위해 시스템은 다음 세 가지 계층에서 스킬을 로드합니다.

계층	로드될 때	대상 크기
Frontmatter (`name` + `description`)	항상 - 시작 시	~100 토큰
`SKILL.md` body	스킬 발동 시	토큰 5,000개 미만(1,500-2,000단어)
참고 자료 (`references/`)	에이전트가 요청 시	Unlimited
스크립트 (`scripts/`)	실행됨, 컨텍스트에 로드되지 않음	N/A

에이전트가 하위 디렉터리의 존재를 알 수 있도록 하위 디렉터리를 명시적으로 SKILL.md참조합니다.

## Additional Resources

- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility

3단계: 커넥터 추가(선택 사항)

확장이 외부 데이터에 액세스해야 하는 경우 원격 MCP 서버를 추가합니다. 이 단계는 선택 사항입니다. 스킬 전용 패키지는 프롬프트 기반 워크플로에 적합합니다.

Tip

서버가 클라이언트에 따라 도구 표시 여부를 제어하거나 유입 트래픽을 식별하는 경우, Cowork가 제시하는 클라이언트 ID는 서버에 대한 Cowork 트래픽 식별에서 확인하세요.

비고

사용자 지정 플러그인은 모바일용 Cowork에서 지원되지 않습니다.

커넥터 요구 사항

Requirement	Details
Transport	스트리밍 지원 HTTP(HTTPS 필요, TLS 1.2 이상)
Protocol	JSON-RPC 2.0 메시지 형식
도구 발견	동적 검색을 위한 `tools/list` 지원(권장)
도구 실행	호출을 위한 `tools/call` 지원
Availability	스토어에 게시된 앱에 권장되는 99.9% 가동 시간 SLA
응답 시간	도구 호출당 30초 미만

도구 설계 지침

작은 API의 경우 작업마다 도구 하나(15개 미만의 작업): search_case_law, get_ruling, cite_precedent
검색 + 실행 대규모 API(작업 50개 이상)의 경우: search_actions + execute_action
설명이 포함된 이름: get_bond_price 아닌 getData
풍부한 입력 스키마: 모든 매개 변수에 대한 설명을 포함합니다. 에이전트가 읽는 내용입니다.
구조화된 출력: 에이전트가 사용자를 위해 형식을 지정할 수 있는 JSON을 반환합니다.
파일 입력: 사용자의 작업 영역에서 파일을 허용하려면 contentEncoding: base64로 매개 변수를 선언합니다. 자세한 내용은 Cowork 작업 영역에서 파일 받기에서 확인하세요.

커넥터의 도구를 설명하세요(`mcpToolDescription`)

커넥터는 remoteMcpServer 필요에 따라 mcpToolDescription 개체를 포함할 수 있습니다. 제공되는 경우, 해당 중첩 file 속성은 .zip 안에 패키징한 도구 설명 JSON 파일을 가리키며, 이 파일은 패키지 루트에서의 상대 경로로 참조됩니다. Cowork는 MCP 서버에서 도구를 동적으로 검색하고 이 파일이 있더라도 사용하지 않습니다.

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  },
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
  }
}

mcpToolDescription를 포함하는 경우 참조된 파일(예: tools/contoso-legal-tools.json)은 커넥터가 노출하는 도구를 설명하며 ZIP 패키지에 있어야 합니다. 플러그인을 패키지할 때 manifest.json 및 skills/ 폴더와 함께 포함하세요.

Tip

이 요구 사항은 매니페스트 버전 1.28에 적용됩니다. mcpToolDescription가 생성하는 패키지는 1.29를 대상으로 하며, agentConnectors[] 항목은 URL 전용이고 wiqd plugin create는 선택 사항이며, 잊어버릴 도구 설명 파일도 없습니다.

지원되는 인증 유형

인증 유형	사용 시기	사용자 환경
`None`	공개 또는 익명 API, 내부 서비스	투명 - 인증 프롬프트 없음
`OAuthPluginVault`	OAuth 2.0 API(프로덕션 환경에 권장됨)	사용자가 OAuth 동의를 한 번 완료합니다.
`ApiKeyPluginVault`	API 키 기반 서비스	사용자가 키를 한 번 제공합니다

비고

API 키 인증에 대한 지원은 아직 Cowork에서 사용할 수 없습니다.
MCP 서버에 API 키가 필요한 경우, 대신 OAuthPluginVault 또는 동적 클라이언트 등록을 사용하거나 None를 허용하는 엔드포인트를 노출하세요.

LOB(기간 업무) API에 대한 플러그 인 빌드에서 Entra로 보호되는 MCP 엔드포인트를 통해 Cowork를 API 키로 보호된 서비스에 연결하는 참조 패턴을 찾을 수 있습니다.

OAuthPluginVault 및 ApiKeyPluginVault의 경우 referenceId는 Microsoft Enterprise Token Store에 저장된 자격 증명을 가리킵니다. 비밀은 매니페스트나 기술 파일에 절대 포함되지 않습니다. referenceId 값은 Agents Toolkit에 OAuth 클라이언트를 등록할 때 생성하는 OAuth 클라이언트 등록 ID입니다.

Important

OAuth 클라이언트를 등록할 때 플러그인이 테넌트 간에 작동하도록 조직별 사용 설정을 모든 Microsoft 365 조직으로 설정합니다.

MCP 인증

인증에 OAuth 또는 ApiKey를 사용하려면 설정 및 구성에 대한 자세한 내용은 Microsoft 365 Copilot의 에이전트에서 MCP 및 API 플러그인에 대한 인증 구성을 참조하세요.

동적 클라이언트 등록

MCP 서버가 DCR(동적 클라이언트 등록)을 지원하는 경우 커넥터 정의에서 authentication 구성을 생략할 수 있으며 Cowork는 플러그인을 대신하여 OAuth 클라이언트를 자동으로 만듭니다.

비고

authentication 구성을 생략하는 것은 Cowork에서만 지원됩니다. Copilot Chat에서는 지원되지 않습니다. 플러그 인이 Copilot Chat에서도 작동해야 하는 경우 OAuthPluginVault에 설명된 대로 인증을 구성합니다.

authorization 개체 전체를 생략할 수 있습니다. MCP 서버 URL을 구성하면 Cowork가 OAuth 클라이언트를 자동으로 처리해 줍니다.

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp"
}

4단계: 매니페스트 만들기

manifest.json를 패키지 루트에 만듭니다. 이 예제에서는 매니페스트 버전 1.28을 사용합니다. 반면 wiqd plugin create는 커넥터 항목에 URL만 지정하는 버전 1.29를 고정하여 사용합니다.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "YOUR-GUID-HERE",
  "developer": {
    "name": "Contoso Legal Tech",
    "websiteUrl": "https://contoso.com",
    "privacyUrl": "https://contoso.com/privacy",
    "termsOfUseUrl": "https://contoso.com/terms"
  },
  "name": {
    "short": "Contoso Legal Tools",
    "full": "Contoso Legal Tools for Copilot Cowork"
  },
  "description": {
    "short": "Contract analysis, clause extraction, and legal research",
    "full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    { "folder": "./skills/contract-analysis" }
  ]
}

커넥터를 추가하려면 agentConnectors를 포함합니다.

{
  "agentConnectors": [
    {
      "id": "contoso-legal-api",
      "displayName": "Contoso Legal Database",
      "description": "Access to case law, statutes, and regulatory databases",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://api.contoso.com/legal/mcp",
          "mcpToolDescription": {
            "file": "./tools/contoso-legal-tools.json"
          },
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
          }
        }
      }
    }
  ]
}

커넥터 구성에서 referenceId는 OAuth 등록 ID여야 합니다. mcpToolDescription를 포함하는 경우 해당 file은 ZIP 패키지에 포함된 도구 설명 JSON 파일을 가리켜야 합니다.

Important

v1.28 매니페스트 스키마는 엄격합니다. additionalProperties: false가 루트에 설정되므로 스키마에 정의되지 않은 필드는 거부됩니다. 표준 Teams 앱 매니페스트에서 유효한 필드(예: packageName)는 Property 'packageName' has not been defined and the schema does not allow additional properties.와 같은 오류로 인해 업로드가 실패할 수 있습니다. 여기에 표시된 필드만 포함하세요.

5단계: 아이콘 추가

PNG 아이콘 2개를 생성하세요.

Icon	크기	Purpose
`color.png`	192×192 px	스토어 및 앱 목록에 표시된 풀 컬러 앱 아이콘
`outline.png`	32×32 픽셀	컴팩트 보기를 위한 단색 윤곽선 아이콘

아이콘이 아직 없는 경우 atk import openplugin은 단색 자리 표시자를 생성합니다. 스토어에 제출하기 전에 교체하세요.

6단계: 패키징

루트 수준에서 모든 콘텐츠가 포함된 ZIP 파일을 만듭니다. (wiqd plugin provision 이후에 wiqd plugin package가 이와 동일한 구조를 생성합니다.)

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

커넥터에 mcpToolDescription가 포함되어 있으면, 해당 항목이 참조하는 도구 설명 JSON 파일을 포함하세요. 기술 전용 패키지를 포함하여 mcpToolDescription를 사용하지 않는 패키지에는 tools/ 폴더가 필요하지 않습니다.

Windows(PowerShell):

Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip

macOS/Linux:

zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/

Microsoft 365 에이전트 도구 키트 사용

 atk package --manifest-file ./appPackage/manifest.json \
       --output-package-file ./appPackage/build/appPackage.zip \
       --output-folder ./appPackage/build

7단계: 테스트

앱을 테스트하려면 Teams에 앱 업로드에 설명된 대로 앱 패키지를 Teams에 업로드합니다.

wiqd를 사용하여 플러그인을 빌드한 경우, 대신 wiqd plugin provision를 실행하세요. wiqd가 테넌트에 플러그인을 대신 등록해 줍니다. 수동으로 빌드한 패키지를 개인적으로 테스트하려면 Microsoft 365 Agents Toolkit 명령줄 인터페이스를 사용하여 앱을 사이드로드합니다.

npm에서 @microsoft/m365agentstoolkit-cli 설치:

npm install -g @microsoft/m365agentstoolkit-cli

다음을 실행하여 설치를 확인하세요.
```
atk --version
```
Microsoft 365 회사 계정으로 인증:
```
atk auth login
```
업무 계정에 로그인한 다음 에이전트 패키지를 설치하세요. 파일 경로를 ZIP 패키지 위치로 바꾸세요.
```
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
```
설치에 성공하면 계정에 대한 AppId 및 TitleId가 포함된 출력이 반환됩니다.
나중에 업데이트하거나 제거할 때 사용할 수 있도록 이 ID를 저장하세요.

Microsoft 365 에이전트 툴킷 명령줄 인터페이스에서 자세히 알아보세요.

8단계: 테넌트에 게시

관리 센터에서 패키지를 업로드하여 플러그인이 조직 내 모든 사용자가 찾을 수 있는 Discover 섹션에 표시되도록 하세요.

열기 M365 관리 센터>앱 관리>사용자 지정 앱 업로드.
줄임표 단추(...)를 선택합니다. >에이전트 추가.
패키지를 .zip 업로드하세요.
Cowork>소스 및 기술>플러그인을 엽니다. 플러그인이 Discover 섹션에 표시됩니다.

wiqd plugin share는 플러그인을 검색이 아닌 나와 공유됨에 배치합니다. 테스트 및 특정 사용자에 대한 대상 배포에 사용합니다. 관리 센터에 업로드해야 플러그인이 검색 가능 목록에 표시됩니다.

9단계: 일반에 공개

공개 배포용 플러그인의 경우 파트너 센터를 통해 Microsoft 365 App Store에 플러그인을 제출하세요. 자세한 내용은 Microsoft 365 Copilot용 에이전트 게시에서 확인하세요.

로컬 MCP 서버에 대해 커넥터 테스트

커넥터에는 HTTPS mcpServerUrl가 필요합니다. 로컬 컴퓨터에서 실행 중인 서버를 테스트하려면 공개 HTTPS URL을 통해 외부에서 접근할 수 있도록 해야 합니다. 개발 터널은 TLS를 종료하는 릴레이를 제공합니다.

devtunnel port create <tunnel> -p <port> --protocol http

Important

--protocol http이 아니라 https을 사용합니다. --protocol 플래그는 공용 터널 URL이 아닌 터널이 전달하는 로컬 서비스를 설명합니다. 대부분의 로컬 MCP 서버는 일반 HTTP를 사용하므로 서버가 HTTP를 제공하는 동안 --protocol https를 설정하면 터널을 통과하는 모든 요청이 502 오류를 반환합니다. 릴레이는 TLS를 종료하고 이 플래그에 관계없이 HTTPS를 통해 공용 URL을 제공합니다.

Troubleshooting

증상	원인	수정
터널링된 모든 요청은 `502`를 반환하며 로컬 서버는 HTTP를 사용합니다	`devtunnel port create`가 `--protocol https`로 실행되었습니다.	다음을 사용하여 포트 다시 만들기 `--protocol http`
로컬 서버가 실행 중인데도 macOS에서 터널링된 요청이 `502`를 반환함	서버는 `0.0.0.0`(IPv4 전용)에 바인딩되어 있지만, 터널은 `localhost`에 연결을 시도하며, 먼저 `::1`(IPv6)로 확인됩니다	IPv4 및 IPv6 연결을 모두 허용하도록 서버를 `::` 바인딩합니다.
업로드가 `Property '<field>' has not been defined and the schema does not allow additional properties`로 인해 실패함	매니페스트에는 v1.28 스키마에서 허용하지 않는 필드(예: `packageName`)가 포함되어 있습니다.	필드를 제거합니다. v1.28 스키마는 `additionalProperties: false`를 사용합니다

패키징 패턴

확장에 맞는 패턴을 선택합니다.

기술만(커넥터 없음)

프롬프트 기반 워크플로, 문서 분석 및 작성 지원에 가장 적합합니다.

my-skills-pack.zip
├── manifest.json          # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
    ├── skill-one/SKILL.md
    └── skill-two/SKILL.md

기술 + 원격 커넥터

데이터 분석, API 통합 및 엔터프라이즈 시스템에 가장 적합합니다.

my-data-skills.zip
├── manifest.json          # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

커넥터만(사용자 지정 기술 없음)

Cowork의 기본 제공 기술이 이미 지원하는 데이터 원본에 이 옵션을 사용하세요.

my-connector.zip
├── manifest.json          # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
    └── my-connector.json

가져온 Claude Code 또는 Cursor 플러그인

Cowork를 대상으로 하는 기존 Claude 에코시스템 플러그인에는 이 옵션을 사용하세요. Microsoft 365에서 플러그인 개발을 계속하려면 플러그인을 가져오세요.

wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

현재 플러그인 상태를 기준으로 배포 가능한 .zip 파일을 만들려면 변환 스크립트를 사용하세요.

atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

기술 작성 모범 사례

안정적으로 활성화되고 일관된 결과를 생성하는 기술을 만들려면 다음 지침을 따르세요.

효과적인 설명 작성

description 필드는 에이전트가 기술을 활성화할 시점을 결정합니다. 구체적으로:

# Good-specific trigger phrases, concrete scenarios
description: |
  Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
  Use when user asks to "analyze bond spreads", "compare bonds",
  "rich-cheap analysis", "relative value", or "Z-spread calculation".

# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.

효과적인 워크플로 작성

설명은 구체적으로 작성합니다. "사용자가 요청할 때 사용..." 트리거 문구를 포함하세요. 이 설명은 에이전트가 활성화할 기술을 결정하는 방법입니다.
워크플로로 구조화합니다. 단계에 번호를 매깁니다. 각 단계는 구체적인 작업(파일 읽기, 도구 호출, 출력 생성)에 매핑되어야 합니다.
출력 형식을 정의합니다. 사용자가 기대해야 하는 정확한 테이블, 목록 또는 문서 구조를 표시하세요. 이 정의는 일관성을 크게 개선합니다.
도구 이름을 명시하기. 기능이 커넥터 도구에 의존하는 경우 해당 도구의 이름을 명시적으로 지정합니다. "search_case_law 도구를 사용하여..."
메인 SKILL.md를 간결하게 유지하세요. 자세한 참조 자료를 references/ 하위 디렉터리로 이동합니다. 기술 본문에는 백과사전식 설명이 아니라 작업 절차를 담아야 합니다.

일반적인 실수 방지

파일에 SKILL.md. agentConnectors를 API 자격 증명 인증과 함께 사용합니다.
기본 제공 기술을 복제하지 마세요. 빌드하기 전에 내장 스킬 목록을 확인하세요.
스킬을 너무 광범위하게 만들지 마십시오. "법률 문서와 관련된 모든 작업 수행"은 "계약 분석", "조항 추출", "법률 조사"와 같은 구체적인 전문 기능보다 효과가 떨어집니다.
파일 경로를 하드 코딩하지 마세요 또는 시스템 명령을 사용하지 마세요. 역량은 여러 환경에 걸쳐 활용할 수 있어야 합니다.
모든 것을 SKILL.md에 넣지 마십시오. 본문이 ~3,000단어를 초과하는 경우 자세한 내용을 references/로 이동하세요.

유효성 검사 규칙

패키지를 제출하면 플랫폼이 여러 수준에서 패키지의 유효성을 검사합니다. 반려를 피하려면 제출하기 전에 이러한 오류를 수정하세요.

업로드 시점이 아니라 빌드 중에 이를 포착하려면 wiqd plugin validate --mode deep를 실행하세요. 이 명령은 플러그인을 패키징하고 로컬에서 이와 동일한 규칙을 실행합니다. 3단계: 빌드하면서 유효성을 검사에서 자세히 알아보세요.

매니페스트 수준 유효성 검사

코드	규칙	Severity
ASKILL-M001	`folder`는 각 `agentSkills` 항목마다 필요합니다.	Error
ASKILL-M002	`agentSkills` 배열에는 최대 20개 항목이 있을 수 있습니다.	Error
ASKILL-M003	`folder` 경로에는 최대 256자까지 사용할 수 있습니다.	Error

패키지 수준 유효성 검사

코드	규칙	일반적인 해결 방법	Severity
ASKILL-P001	매니페스트에서 참조된 폴더가 ZIP에 있습니다	ZIP 구조를 확인하세요	Error
ASKILL-P002	폴더에 `SKILL.md` 파일이 포함되어 있습니다	누락된 `SKILL.md` 추가	Error
ASKILL-P003	`SKILL.md`에는 `---` 구분 기호 사이에 유효한 YAML 프런트매터가 있습니다.	YAML 구문 수정	Error
ASKILL-P004	Frontmatter에 `name` 필드가 포함됨	프런트매터에 `name:` 추가	Error
ASKILL-P005	Frontmatter에 `description` 필드가 포함됨	프런트매터에 `description:` 추가	Error
ASKILL-P006	`name` 폴더 이름(마지막 경로 세그먼트)과 일치합니다.	폴더 이름 바꾸기 또는 `name:` 수정	Error
ASKILL-P007	`name` 는 kebab-case입니다.	`my-skill`를 사용하고 `MySkill` 또는 `my_skill`는 사용하지 마세요	Error
ASKILL-P008	배열에 중복 `folder` 값이 없음	중복된 이름 제거	Error

커넥터 유효성 검사

규칙	Severity
각 커넥터에는 `id` 및 `displayName`가 필요합니다	Error
모든 커넥터 `id` 값은 매니페스트 내에서 고유해야 합니다	Error
정확히 `plugin` 또는 `remoteMcpServer` 중 하나	Error
`mcpServerUrl` 는 유효한 HTTPS URL이어야 합니다.	Error
`mcpToolDescription`가 있으면 해당 `file`가 ZIP에 있어야 합니다.	Error
`authorization.referenceId`은(는) `None` 형식인 경우를 제외하고 필수	Error
`authorization.referenceId`는 형식이 `None`일 때 있으면 안 됩니다	Error

보조 파일 유효성 검사

포털은 업로드 및 동기화 시점에 SKILL.md와 함께 업로드되는 관련 파일(참조 자료, 스크립트 및 기타 파일)의 유효성을 검사합니다.

규칙	Severity
스킬당 최대 20개의 컴패니언 파일( `SKILL.md`제외)	Error
각 첨부 파일은 5MB 이하여야 합니다	Error
기술당 전체 보조 파일의 용량은 10MB 이하여야 합니다	Error
파일 경로는 상대 경로여야 합니다(절대 경로 불가).	Error
경로 통과 세그먼트(`..`)는 없습니다	Error
파일 이름에 백슬래시 또는 null 바이트 없음	Error
숨김 파일(이름이 `.`로 시작하는) 없음	Error
Windows 예약된 이름 없음 (`CON`, `AUX`, `NUL`, `COM1`, `COM9`–`LPT9`, `LPT1`–`PRN`)	Error
파일 이름에는 안전한 문자만 사용해야 합니다(영숫자, 하이픈, 밑줄, 점, 공백 등 `!`).	Error

플랫폼 간 호환성

기술은 에이전트 기술 오픈 표준을 사용합니다. 여러 AI 도구에서 동일한 SKILL.md 파일이 작동합니다.

Platform	Compatibility
클로드 코드	완전히 동일한 `SKILL.md` 형식
Claude.ai 프로젝트	Full-skills는 프로젝트 파일로 업로드할 수 있습니다.
VS Code/GitHub Copilot	에이전트 모드에서 지원되는 Full-Agent 스킬
Gemini CLI	전체 에이전트 스킬 지원
JetBrains Junie	전체 에이전트 스킬 지원
OpenAI 코덱스	전체 에이전트 스킬 지원
Cursor	전체 에이전트 스킬 지원

Claude Code와 Copilot Cowork 모두를 위한 기능을 개발하는 경우 wiqd로 플러그인을 작성하세요. 그런 다음 wiqd plugin export --format claude-plugin을 실행하여 Claude 코드 레이아웃을 생성합니다. Claude Code 플러그인 구조(상위 집합)에서 시작하는 것을 선호한다면, 레이아웃은 다음과 같습니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Claude plugin manifest
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md       # Works in both Claude Code AND M365
│   │   └── references/
│   └── skill-two/
│       └── SKILL.md
└── .mcp.json              # MCP server config (optional)

Microsoft 365 앱 스토어에 게시할 준비가 되면 wiqd plugin import 또는 변환 스크립트를 사용해 플러그인을 Microsoft 365로 가져오세요.

atk import openplugin --path ./my-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

MCP 주석 및 확인 관리

Copilot Cowork는 서버가 annotations에서 반환하는 도구의 표준 MCP tools/list 개체를 읽고 이를 사용하여 도구 호출에 사용자 확인이 필요한지 여부와 프롬프트에 표시할 레이블을 결정합니다.

사용 가능한 필드

Field	Type	Effect
`readOnlyHint`	bool	`false`: 도구가 실행되기 전에 확인이 필요합니다.
`destructiveHint`	bool	`true`: 도구가 실행되기 전에 확인이 필요합니다.
`title`	string	확인 대화 상자에 표시된 사용자가 읽을 수 있는 레이블입니다. 없는 경우 도구 이름으로 대체합니다.

확인 규칙

destructiveHint == true 또는 readOnlyHint == false인 경우 확인이 필요합니다.

모든 도구에는 안전 주석이 지정되어 있어야 합니다. 주석이 없는 도구는 파괴적인 것으로 처리되므로 확인이 필요합니다. MCP 스키마 참조에서 자세히 알아보세요.

MCP 예제

알기 쉬운 레이블이 있는 파괴적인 작업:

{
  "name": "send_email",
  "description": "Send an email message.",
  "annotations": {
    "title": "Send Email",
    "destructiveHint": true
  },
  "inputSchema": { ... }
}

자동 실행되는 안전 읽기:

{
  "name": "search_docs",
  "annotations": {
    "title": "Search Documents",
    "readOnlyHint": true
  }
}

지금 사용 가능한 항목

Microsoft 도구(Graph, Dataverse 등)는 주석에 관계없이 Cowork의 기본 제공 정책에 의해 제어됩니다.
비 Microsoft MCP 서버의 경우 주석 기반 확인이 점진적으로 롤아웃되고 있습니다. 이제 힌트 설정은 이전 버전과 호환되며, 개발자 변경 없이 출시가 확장됨에 따라 확인 프롬프트가 표시됩니다.

Cowork 작업 영역에서 파일 받기

커넥터 도구는 사용자의 Cowork 세션에서 파일(사용자가 첨부한 문서, Cowork에서 저장한 이메일 첨부 파일 또는 이전 단계에서 생성된 파일)을 입력으로 가져올 수 있습니다. 표준 JSON Schema 키워드인 contentEncoding: base64를 사용해 매개 변수를 선언하면 나머지는 Cowork가 처리합니다. Microsoft 관련 스키마 확장이 필요하지 않으며 서버의 API 표면이 변경되지 않습니다.

Cowork는 서버를 호출하기 전에 작업 영역 파일을 찾아 이를 base64로 인코딩하므로 파일 바이트가 에이전트의 컨텍스트에 들어가지 않습니다. 에이전트는 오직 작업 영역의 파일 경로만 확인하고 출력합니다.

비고

에이전트에게 파일 자체를 base64로 인코딩하고 도구 호출에 blob을 붙여넣도록 지시하지 마세요. 이 방법은 전체 파일을 모델의 컨텍스트에 로드하고 모델이 Blob을 정확하게 재현하는 데 의존합니다. 작은 테스트 파일에서는 작동하는 것으로 보이지만 실제 파일에서는 실패합니다.

파일 매개변수 선언

contentEncoding: base64가 있는 문자열 속성은 파일 입력으로 인식됩니다.

{
  "name": "analyze_contract",
  "description": "Extract key terms from a contract document.",
  "annotations": {
    "title": "Analyze Contract",
    "readOnlyHint": true
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "document": {
        "type": "string",
        "contentEncoding": "base64",
        "description": "The contract file to analyze."
      },
      "jurisdiction": {
        "type": "string",
        "description": "Two-letter country code governing the contract."
      }
    },
    "required": ["document"]
  }
}

여러 파일을 허용하는 도구의 경우 이러한 문자열의 배열도 인식됩니다.

"attachments": {
  "type": "array",
  "items": { "type": "string", "contentEncoding": "base64" },
  "description": "Receipt images to attach to the expense line."
}

에이전트가 보는 내용

inputSchema.properties의 최상위 수준에서 선언된 파일 매개 변수의 경우 Cowork는 모델 대상 스키마에서 이를 단일 direct_attachment_file_paths 배열로 대체하는데, 이 배열은 Cowork의 기본 제공 도구가 사용하는 것과 동일한 매개 변수이므로 에이전트는 이미 이를 채우는 방법을 알고 있습니다. 위의 스키마는 에이전트에 다음과 같이 표시됩니다.

{
  "type": "object",
  "properties": {
    "direct_attachment_file_paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Workspace file paths to attach."
    },
    "jurisdiction": { "type": "string" }
  }
}

도구에서 둘 이상의 최상위 파일 매개 변수를 선언하면 모두 단일 direct_attachment_file_paths 배열로 축소됩니다. 호출 시 Cowork는 해결된 파일을 선언 순서대로 원래 매개 변수 이름으로 팬아웃합니다.

중첩된 파일 매개변수

에이전트는 개체 또는 개체 배열 내에 중첩된 파일 매개 변수를 지원합니다. 에이전트는 이 매개 변수를 다른 방식으로 처리합니다. 즉, 매개 변수를 축소하는 대신 에이전트가 해당 매개 변수를 자체 위치에서 제자리에서 경로 문자열로 다시 씁니다. 이 방법은 파일과 해당 형제 필드 간의 연결을 유지합니다. 예를 들어 비용 라인당 하나의 영수증을 받습니다.

"line_items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" },
      "receipt": { "type": "string", "contentEncoding": "base64" }
    }
  }
}

에이전트는 line_items[].receipt를 작업 공간 경로로 채우고, Cowork는 호출을 전달하기 전에 각 경로를 해당 위치에서 base64 콘텐츠로 바꿉니다.

중첩은 최상위 inputSchema 아래로 4개 수준 깊이까지 트래버스됩니다. $ref 포인터는 따라가지 않으므로 파일 매개 변수는 $ref 뒤에 두지 말고 인라인으로 정의합니다.

서버가 수신하는 항목

서버는 base64로 인코딩된 콘텐츠로 채워진 원래 매개 변수 이름이 있는 일반 tools/call를 받습니다.

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

서버는 에이전트가 경로 기반 인터페이스를 사용했음을 알 필요가 없으며 contentEncoding: base64 매개 변수를 선언하지 않는 도구는 영향을 받지 않습니다.

Limits

Limit	Value
도구 호출당 Files	8
파일당 크기	150 MiB
도구 호출당 총 크기	150 MiB
도구별 배열 파일 매개변수	1(임의 개수의 스칼라 파일 매개 변수와 결합)
최대 중첩 깊이	맨 위에서 4단계 아래 `inputSchema`

파일 수 또는 크기 제한을 초과하는 호출은 도구 오류로 실패하고 서버에 도달하지 못합니다. 150MiB 상한선을 염두에 두고 API 및 시간 제한의 크기를 조정하세요. base64는 페이로드를 원시 파일 크기보다 약 1/3 더 커지며, 인코딩된 콘텐츠는 JSON-RPC 요청 본문으로 전송됩니다.

Recommendations

사람 독자를 위한 매개 변수를 설명합니다. 에이전트는 설명을 사용하여 어떤 파일이 어떤 매개변수에 대응하는지 결정합니다. 예를 들어, "The signed contract PDF to analyze"는 "file"보다 더 잘 작동합니다.
매개 변수 설명에 허용하는 형식을 지정합니다. Cowork는 사용자가 첨부하는 모든 항목을 그대로 전달합니다. 사용자 측에서 콘텐츠 유형을 확인하고, 사용할 수 없는 경우 명확한 도구 오류를 반환하세요.
주석을 설정합니다. 파일을 받아서 처리하는 도구는 일반적으로 읽기 전용이 아니므로 확인 메시지를 표시합니다. MCP 주석 및 확인 관리에 대해 자세히 알아보세요.
파일 매개변수를 인라인으로 유지하세요. / $ref뒤에 있거나 4개 수준보다 더 깊게 중첩된 매개 변수는 다시 작성되지 않습니다. 서버는 콘텐츠를 기대하는 곳에 경로 문자열을 받게 됩니다.
도구당 최대 하나의 배열 파일 매개 변수를 선언합니다. 두 개 이상의 파일이 있는 경우 Cowork는 어떤 파일이 어떤 배열에 속하는지 알 수 없으며 도구 오류로 호출이 실패합니다. 하나의 배열 또는 여러 스칼라 매개 변수를 사용하거나 스칼라와 단일 배열을 혼합하여 사용합니다.
스칼라 전용 도구에 대한 정확한 개수를 확인하세요. 도구가 스칼라 파일 매개 변수만 선언하는 경우 에이전트가 전달하는 파일 수는 선언된 수와 일치해야 합니다. 에이전트가 누락하거나 과도하게 제공하지 않도록 설명에 선택적 파일 매개 변수를 명확하게 표시합니다.

비고

이 메커니즘은 MCP 파일 업로드 작업 그룹에서 표준화하고 있는 모델 컨텍스트 프로토콜 자체의 파일 입력 관련 작업보다 앞서 나왔습니다. Cowork는 해당 표준이 도입되면 선언적 파일 입력의 표준화된 형식에 대한 지원을 추가할 수 있습니다. 여기에 설명된 contentEncoding: base64 계약은 계속 작동합니다.

서버에 대한 Cowork 트래픽 식별

MCP 서버가 클라이언트별로 도구 가시성을 제한하거나 수신하는 트래픽의 출처를 식별하려는 경우 Cowork에서 오는 요청을 인식할 수 있습니다. Cowork는 두 가지 채널에서 안정적인 소프트웨어 정체성을 보여줍니다.

Channel	표시되는 위치	Value
`User-Agent` 요청 헤더	Cowork가 귀하의 서버로 보내는 모든 아웃바운드 요청	`copilot-cowork/1.0`
`clientInfo`의 MCP `initialize` 핸드셰이크에서	`initialize` 요청만	`{ "name": "copilot-cowork", "version": "<version>" }`

`copilot-cowork` 접두사와 일치

두 채널 중 어느 쪽에서든 대소문자를 구분하지 않고 copilot-cowork접두사와 일치시킵니다. 정확한 copilot-cowork/1.0 문자열 또는 특정 clientInfo.version과 일치시키지 마세요. 버전은 클라이언트 ID 계약을 추적하며 변경될 것으로 예상됩니다. 접두사 일치는 버전 업데이트 시에도 게이트가 계속 작동하도록 합니다.

# Correct: case-insensitive prefix match
copilot-cowork

# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0

게이트에 적합한 채널을 선택하세요

두 채널의 범위는 서로 다르므로 서버가 게이트를 적용하는 방법과 일치하는 것을 기준으로 삼아야 합니다.

User-Agent 헤더는 tools/list 및 를 포함한 tools/call 요청에 존재합니다. 요청별로 제한하거나 사용량을 집계하려면 이 헤더를 기준으로 삼으세요.
clientInfo는 핸드셰이크 중에 initialize 전송됩니다. 연결 시 세션당으로 제한하면 여기서 읽을 수 있지만 이후 요청에서는 반복되지 않습니다.

ID에 포함되는 내용과 포함되지 않는 내용

ID는 소프트웨어의 이름만 지정합니다. 모든 Cowork 사용자 및 연결에 대해 동일하며 사용자 신원을 전달하지 않습니다. 사용자 ID는 커넥터의 인증 구성이 정의하는 권한 부여 흐름 내에 유지됩니다.

ID에 포함되는 사항	ID에는 포함되지 않음
안정적인 소프트웨어 이름(`copilot-cowork`) 및 계약 버전	모든 테넌트, 사용자, 세션 또는 대화 식별자
각 요청과 각 연결마다 동일한 값	커넥터별 한정자

커넥터별 한정자가 없으므로 현재 이 ID를 사용하여 어떤 커넥터가 호출했는지 식별하거나 게시된 Microsoft 플러그 인을 동일한 URL을 가리키는 사이드로드된 서버에서 구분할 수 없습니다. 이러한 구분이 필요한 경우 클라이언트 ID가 아닌 커넥터의 권한 부여 구성을 통해 적용합니다.

자주 묻는 질문

Claude Code에서 M365 패키지의 기술을 사용할 수 있나요?

Yes. 기술 폴더에는 표준 에이전트 기술이 포함되어 있습니다. wiqd plugin export --format claude-plugin을 실행하여 Claude Code 레이아웃을 생성하거나, 기술 폴더를 아무 Claude Code 프로젝트의 .claude/skills/에 복사합니다.

원격 커넥터가 필요한가요?

No. 스킬 전용 패키지는 프롬프트 기반 워크플로에 적합합니다. 커넥터는 스킬에 외부 시스템의 실시간 데이터가 필요한 경우에만 필요합니다.

플러그인 스킬은 기본 제공 스킬과 어떻게 다른가요?

플러그인 기술은 API에서 소스 "package"와 함께 표시됩니다. 같은 이름의 기본 제공 기술을 재정의할 수 없습니다. 관리자가 배포한 패키지가 isAdminDeployed: true를 표시합니다.

IT 관리자가 사용 가능한 플러그 인을 제어할 수 있나요?

Yes. 표준 M365 관리자 제어 기능에는 테넌트 수준의 허용/차단 목록, 관리자가 관리하는 배포 및 규정 준수 정책이 적용됩니다.

플러그 인이 철회되면 어떻게 되나요?

다음 동기화 주기에 해당 패키지의 기술과 커넥터가 사용자 세션에서 제거됩니다. 활성 대화는 중단되지 않지만 새 세션에는 패키지의 기능이 없습니다.

패키지당 최대 스킬 수는 어떻게 됩니까?

20개의 스킬(ASKILL-M002 기준). 커넥터의 경우 패키지당 10개로 제한됩니다.

스킬이 동일한 패키지의 커넥터 도구를 참조할 수 있나요?

네, 그렇게 해야 합니다. SKILL.md 워크플로에서 도구의 이름을 명시적으로 지정합니다(예: "search_case_law 도구를 사용하여..."). 에이전트는 런타임에 이들을 연결합니다.

플러그인의 도구가 Cowork 작업 영역의 파일을 받을 수 있나요?

Yes. 도구 매개변수를 contentEncoding: base64로 선언하면 Cowork가 서버를 호출하기 전에 사용자의 작업 영역 파일을 Base64 콘텐츠로 변환합니다. 모델은 파일 내용이 아니라 파일 경로를 전달하므로 대용량 파일이 모델의 컨텍스트를 소모하지 않습니다. 선언 세부 정보 및 제한에 관해서는 Cowork 작업 영역에서 파일 수락에서 자세히 알아보세요.

패키지에 대한 결정적 GUID를 생성하려면 어떻게 해야 하나요?

wiqd plugin create가 앱 ID를 생성하고 고정해 줍니다. 변환 스크립트는 플러그인 이름의 UUID v5(SHA-1 기반)를 사용하므로 변환을 두 번 실행하면 동일한 GUID가 생성됩니다. 수동 패키징의 경우 GUID 생성기를 사용하세요. 버전 간에 안정적으로 유지해야 합니다.

어떤 매니페스트 버전을 대상으로 해야 하나요?

wiqd를 사용하여 빌드하는 경우 wiqd가 자동으로 고정해 주므로 1.29를 대상으로 하세요. 1.29에서는 agentConnectors[] 항목은 URL 전용이며 mcpToolDescription는 선택 사항입니다. 이 문서에 수동으로 작성된 예제들은 1.28 버전을 사용하는데, 여기서는 mcpToolDescription이 필수 항목이며, 해당 항목에 명시된 파일은 반드시 ZIP 파일 내에 포함되어 있어야 합니다. atk import openplugin 는 플러그 인 이름에서 UUID v5(SHA-1 기반)를 사용합니다. 가져오기를 두 번 실행하면 동일한 GUID가 생성됩니다. 직접 설정하려면 --app-id를 전달하세요. 수동 패키징의 경우 GUID 생성기를 사용하세요. 버전 간에 안정적으로 유지해야 합니다.

피드백

이 페이지가 도움이 되었나요?

2026-10-22 에 마지막으로 업데이트됨

Copilot Cowork용 플러그인 만들기

빌드할 내용

시작점 선택

wiqd로 플러그인 만들기

1단계: wiqd 설치 및 로그인

2단계: 플러그인을 구성하고 기능 추가

3단계: 구성하면서 유효성 검사

4단계: 프로비저닝, 패키징, 공유

플러그인을 다른 호스트로 옮기기

기존 플러그 인 가져오기

wiqd를 사용하여 가져오기

변환 스크립트를 사용하여 변환

가져올 항목

변환되지 않는 항목

가져오기 옵션

플러그 인 디렉터리로 다시 내보내기

레거시: PowerShell 변환 스크립트

패키지를 수동으로 조립

1단계: 첫 번째 기술 만들기

SKILL.md frontmatter 필드

2단계: 참조 자료 추가(선택 사항)

보조 파일 제한

보조 파일 규칙

3단계: 커넥터 추가(선택 사항)

커넥터 요구 사항

도구 설계 지침

커넥터의 도구를 설명하세요(mcpToolDescription)

지원되는 인증 유형

MCP 인증

동적 클라이언트 등록

4단계: 매니페스트 만들기

5단계: 아이콘 추가

6단계: 패키징

7단계: 테스트

8단계: 테넌트에 게시

9단계: 일반에 공개

로컬 MCP 서버에 대해 커넥터 테스트

Troubleshooting

패키징 패턴

기술만(커넥터 없음)

기술 + 원격 커넥터

커넥터만(사용자 지정 기술 없음)

가져온 Claude Code 또는 Cursor 플러그인

기술 작성 모범 사례

효과적인 설명 작성

효과적인 워크플로 작성

일반적인 실수 방지

유효성 검사 규칙

매니페스트 수준 유효성 검사

패키지 수준 유효성 검사

커넥터 유효성 검사

보조 파일 유효성 검사

플랫폼 간 호환성

MCP 주석 및 확인 관리

사용 가능한 필드

확인 규칙

MCP 예제

지금 사용 가능한 항목

Cowork 작업 영역에서 파일 받기

파일 매개변수 선언

에이전트가 보는 내용

중첩된 파일 매개변수

서버가 수신하는 항목

Limits

Recommendations

서버에 대한 Cowork 트래픽 식별

copilot-cowork 접두사와 일치

게이트에 적합한 채널을 선택하세요

ID에 포함되는 내용과 포함되지 않는 내용

자주 묻는 질문

관련 정보

피드백

추가 리소스

커넥터의 도구를 설명하세요(`mcpToolDescription`)

`copilot-cowork` 접두사와 일치