Tworzenie wtyczek dla usługi Copilot Cowork

Wtyczka to instalowany pakiet, który może zawierać wbudowane lub niestandardowe umiejętności, narzędzia i agenty. Wbudowane umiejętności są dostępne z Copilot. Niestandardowe umiejętności są tworzone przez twórców. Gdy spakujesz niestandardową umiejętność jako wtyczkę, użytkownicy będą mogli ją zainstalować, aby rozszerzyć możliwości rozwiązania Copilot.

Microsoft Copilot Cowork obsługuje rozszerzalność za pośrednictwem pakietów aplikacji M365 — tego samego mechanizmu dystrybucji, który jest używany przez aplikacje usługi Teams, agentów funkcji Copilot i dodatki pakietu Office. Możesz rozszerzyć usługę Cowork o:

  • Umiejętności: Oparte na monitach przepływy pracy, które uczą nowej wiedzy w zakresie współpracy, takich jak analiza finansowa, badania prawne lub przepływy pracy kadr.
  • Łączniki: Zdalne serwery, które zapewniają Cowork dostęp do zewnętrznych źródeł danych i interfejsów API.

Obie aplikacje są pakowane razem w standardowym pakiecie aplikacji Microsoft 365 i dystrybuowane za pośrednictwem sklepu aplikacji Microsoft 365.

Important

Bariery informacyjne w Microsoft Purview (IB) nie są obecnie obsługiwane w przypadku zarządzania wtyczkami lub umiejętnościami oraz ich udostępniania. W dzierżawach, w których włączono IB, przekazywanie osadzonych plików wiedzy jest blokowane na poziomie dzierżawy. Zapobiega to przesyłaniu lub publikowaniu wtyczek i skilli, których dotyczy problem.

Microsoft nie tworzy ani nie obsługuje żadnego trwałego indeksu, grafu wiedzy (w tym Microsoft Graph) ani bazy danych zawierającej zawartość niezależnych dostawców oprogramowania, czy to metodą przeszukiwania, wydobywania, zbierania, zbiorczego eksportu, pozyskiwania ani żadną inną metodą (za pośrednictwem interfejsu API, serwera MCP lub w inny sposób). Microsoft może tymczasowo przetwarzać zawartość niezależnego dostawcy oprogramowania w razie potrzeby, aby odpowiedzieć na zapytanie użytkownika w czasie rzeczywistym, ale nie zachowuje zawartości niezależnego dostawcy oprogramowania poza czasem trwania tej sesji. Na pisemny wniosek niezależnego dostawcy oprogramowania w ciągu 10 dni roboczych Microsoft usuwa wszelkie treści ISV będące w jego posiadaniu lub pod jego kontrolą i pisemnie potwierdza to usunięcie. Dowiedz się więcej na temat ochrony danych w przedsiębiorstwie w usługach Microsoft Copilot i Microsoft Copilot Chat.

Tworzenie a publikowanie<

Tworzenie i pakowanie wtyczki różni się od publikacji w rejestrze, zatwierdzania/przypisywania przez administratora, instalacji użytkownika i logowania do usługi.

  • Narzędzia Work IQ Dev Tools mogą publikować w rejestrze dla wybranej grupy odbiorców.
  • Współdzielenie pracy z określonymi osobami nie wymaga zatwierdzenia przez administratora.
  • Udostępnianie w całej organizacji wymaga zatwierdzenia przez administratora.
  • Bezpośrednie udostępnianie nie jest ofertą w Marketplace.

Aby ułatwić odnajdywanie wtyczek i zarządzanie nimi, zapoznaj się ze wspólnym rejestrem wtyczek. Rejestr wtyczek jest wspólną infrastrukturą Microsoft Copilot, która umożliwia opublikowanie wtyczki tylko raz, aby można było ją odnaleźć przez użytkowników, udostępnić w obsługiwanych środowiskach Copilot i centralnie zarządzać nią przez administratorów. Dowiedz się więcej w usłudze Plugin Hub.

Uwaga / Notatka

Nie każdy spakowany składnik działa w Cowork. Istniejące wtyczki mogą nie zostać automatycznie zmigrowane.

Prerequisites

Użyj tej listy, aby dowiedzieć się, co obsługują wtyczki Cowork i czego wymagają.

  • Kompilowanie wtyczek dla aplikacji Copilot Cowork
    • licencja Microsoft 365 Copilot: wymagana dla użytkowników cowork.
    • Obsługiwana rola administratora: użyj AI Administrator lub Global Administrator w celu zatwierdzenia MCP i zgody dzierżawcy.
  • Narzędzia programistyczne
    • Work IQ Dev Tools: do tworzenia pakietów, walidacji, aprowizacji, udostępniania i żądań publikacji.
    • Microsoft 365 Agents Toolkit: na potrzeby tworzenia agentów i aplikacji oraz tworzenia pakietów aplikacji.
    • Plugin Builder (dawniej Agent Builder): środowisko tworzenia; zakres wdrożenia w potwierdzeniu.
    • Przekazywanie w Cowork: importuje obsługiwane pakiety, a nie pełny przepływ pracy deweloperów.
  • Prawidłowy format pakietu: użyj formatu pakietu aplikacji Microsoft 365 (manifest.json z deklaracjami agentSkills i agentConnectors ).
  • Wymagany schemat: postępuj zgodnie ze standardami manifestu agenta deklaratywnego 1.9 .
  • Sposoby publikacji
    • Bezpośrednie udostępnianie (za pośrednictwem Work IQ Dev Tools lub wiqd plugin share).
    • Przekazywanie organizacyjne (w Centrum administracyjne platformy Microsoft 365 wybierz pozycje Agents>>>).
    • Microsoft Marketplace
  • Licencjonowanie i zgoda
    • Licencja Microsoft 365 Copilot jest wymagana dla każdego użytkownika.
    • Zgoda administratora wymagana dla wtyczki rejestracji mcp i wtyczek połączonych z serwerem.
  • Nadzór i dostęp
    • Wtyczki są zarządzane. Aby je znaleźć, wybierz pozycję Narzędzia w Centrum administracyjne platformy Microsoft 365 i Microsoft Agent 365.
    • Zasady i kontrola kategorii wydawcy. Aby je znaleźć, wybierz Agenci>Ustawienia>Dostęp agentów i wtyczek.
  • Zgodność: jest zgodna z agentskills.io branżowym standardem formatu umiejętności.

Co będziesz tworzyć

Wtyczka Cowork to .zip pakiet zawierający:

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

Skills korzystają z otwartego standardu Agent Skills — tego samego formatu, który obsługują Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie i ponad 30 innych narzędzi AI.

Wybieranie punktu początkowego

Zbuduj swoją wtyczkę za pomocą interfejsu wiersza polecenia wiqd. Interfejs wiersza polecenia tworzy szkielety pakietu i utrzymuje synchronizację między manifest.json a folderami umiejętności. Uruchamia również własne reguły walidacji platformy przed przekazaniem, a następnie aprowizuje i udostępnia wynik. Interfejs wiersza polecenia jest w wersji zapoznawczej, dlatego jego polecenia i wygenerowane dane wyjściowe mogą ulec zmianie przed rozpoczęciem okresu ogólnej dostępności. Wszystko, co generuje, jest zwykłym pakietem aplikacji Microsoft 365, więc nadal możesz bezpośrednio otwierać i edytować pliki oraz obsługiwać ich wersje.

Pakiet należy składać ręcznie tylko wtedy, gdy nie można zainstalować narzędzi lub podczas tworzenia własnego potoku pakowania. W takim przypadku specyfikacja formatu pakietu w tym artykule jest tym, czego potrzebujesz — dokładnie opisuje to, co wiqd produkuje.

Punkt początkowy Wykonaj to Czas do pierwszego pakietu
Zaczynam od zera Tworzenie wtyczki za pomocą narzędzia wiqd około 10 minut
Mam istniejącą wtyczkę Claude Code Przekonwertuj około 5 minut
Nie mogę zainstalować narzędzi albo samodzielnie piszę skrypt pakowania Zmontuj pakiet ręcznie około 30 minut

Zbuduj wtyczkę w wiqd

Interfejs wiersza polecenia wiqd działa zgodnie z tym samym cyklem życia, który w przeciwnym razie wykonujesz ręcznie — tworzenie, dodawanie możliwości, weryfikację, aprowizację, pakowanie i udostępnianie. Tworzony pakiet już spełnia reguły walidacji opisane w tym artykule.

Krok 1. Zainstaluj interfejs wiqd i zaloguj się

Zainstaluj interfejs wiersza polecenia wiqd, postępując zgodnie z przewodnikiem instalacji wiqd, który obejmuje systemy Windows, macOS i Linux. Następnie zaloguj się do dzierżawy platformy Microsoft 365, względem której tworzysz rozwiązanie, ponieważ zarówno aprowizowanie, jak i udostępnianie mają wpływ na dzierżawę:

wiqd auth login --interactive

Instalator rejestruje również wtyczkę CLI usługi GitHub Copilot, dzięki czemu ten sam cykl życia można obsługiwać konwersacyjnie. Na przykład możesz powiedzieć: Utwórz samodzielny plugin o nazwie Pomocnik klasyfikacji lub Sprawdź poprawność mojego pluginu. Ścieżka konwersacji obsługuje te same polecenia, co ta sekcja. Użyj poleceń bezpośrednio podczas tworzenia skryptu potoku lub gdy chcesz uzyskać powtarzalną, nieinterakcyjną automatyzację.

Krok 2: Utwórz strukturę wtyczki i dodaj uprawnienia

Utwórz kontener wtyczek, a następnie dodaj dowolne potrzebne możliwości, w dowolnej kombinacji:

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 szkielety appPackage/skills/contract-analysis/SKILL.md i rejestruje je w pliku agentSkills[]. add connector agentConnectors[] zapisuje wpis. Oba polecenia wymuszają nazewnictwo i limity rozmiaru platformy przed zapisem, więc niezgodność nazwy folderu lub nadmierna długość id nigdy nie dociera do manifestu.

Napisz logikę umiejętności w wygenerowanym pliku SKILL.md. Pola frontmatter, model wczytywania progresywnego i limity pliku towarzyszącego są takie same jak opisano w kroku 1: Tworzenie pierwszej umiejętności i kroku 2: Dodawanie materiałów referencyjnych (opcjonalnie).

Important

wiqd plugin create przypina pakiet do manifestVersion: "1.29", a ręcznie utworzone przykłady w tym artykule używają polecenia 1.28. Różnica ma znaczenie w przypadku złączy. W wersji 1.28 wymagany jest element mcpToolDescription, a plik, którego nazwę określa, musi znajdować się w archiwum ZIP. W wersji 1.29 wpisy agentConnectors[] są tylko adresami URL i mcpToolDescription jest opcjonalne, więc pakiet wygenerowany przez wiqd nigdy nie kończy się niepowodzeniem związanym z przekazywaniem. Interfejs wiqd nie obsługuje jeszcze generowania konfiguracji uwierzytelniania łącznika — skonfiguruj uwierzytelnianie bezpośrednio zgodnie z opisem w części Obsługiwane typy uwierzytelniania.

Krok 3. Weryfikuj podczas tworzenia

Weryfikuj na bieżąco, zamiast przygotowywać pakiet i mieć nadzieję, że przekazywanie zakończy się powodzeniem:

wiqd plugin validate
wiqd plugin validate --mode deep

validate jest statycznym sprawdzaniem w trybie offline w obszarze agenta deklaratywnego. Wtyczka tylko z umiejętnościami lub tylko z łącznikiem przechodzi pozytywnie tę kontrolę, gdy nie ma nic do sprawdzenia, czego można się spodziewać — jest to sprawdzenie cyklu kompilacji, a nie pełne pokrycie validate --mode deep najpierw pakuje wtyczkę, a następnie weryfikuje skompilowaną .zip względem tej samej biblioteki App Validation Library używanej podczas przesyłania. W tym miejscu pojawiają się kody ASKILL i reguły łączników.

Krok 4. Aprowizuj, twórz pakiety i udostępniaj

Uruchom te trzy polecenia w podanej kolejności:

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

Najpierw uruchom provision, ponieważ zapisuje plik środowiskowy, od którego zależą zarówno package, jak i share. Użyj --scope users, aby udostępnić osobom z listy, lub --scope tenant, aby udostępnić wszystkim osobom w organizacji. Tak czy inaczej, wtyczka pojawi się w Udostępnione mi w sekcji Cowork>Źródła i umiejętności>Wtyczki. Aby zamiast tego wymienić pakiet na liście w sekcji Odkryj, administrator go przekazuje. Dowiedz się więcej w części Krok 8. Publikuj w dzierżawie. Aby usunąć to, co utworzył provision, uruchom polecenie wiqd plugin delete --env local --yes.

Przesyłanie do sklepu publicznego jest nadal procesem ręcznym w Centrum partnerskim. Dowiedz się więcej w części Krok 9. Opublikuj publicznie.

Pełne informacje o sposobach publikowania i dalsze wskazówki znajdziesz w artykułach Publikowanie lub udostępnianie wtyczki oraz Udostępnij swoją wtyczkę.

Przenieś wtyczkę do innego hosta

Aby wykorzystać swoje umiejętności w programie Claude Code, Cursor lub innym hoście umiejętności agenta, wyeksportuj projekt zamiast ręcznego kopiować foldery:

wiqd plugin export --format claude-plugin

export ma wartość domyślną --format open-plugin i akceptuje także cursor-plugin. Zapisuje nieskompresowany katalog w obszarze <path>/export/<format>.

Zaimportuj istniejącą wtyczkę

Jeśli masz już wtyczkę Claude Code z umiejętnościami i serwerami MCP, masz dwie ścieżki konwersji. Trasa, którą wybierzesz, zależy od tego, czy planujesz dalej rozwijać wtyczkę, czy po prostu opublikować to, co masz.

Goal Używanie
Kontynuuj tworzenie, weryfikowanie i publikowanie wtyczki z Microsoft 365 wiqd plugin import
Utwórz możliwy do opublikowania element .zip z poziomu istniejącej wtyczki Claude już teraz Skrypt konwersji

Importuj za pomocą interfejsu wiqd

wiqd plugin import rozpoznaje źródło wtyczki Open Plugin, Claude lub Cursor i tworzy z niego projekt wtyczki wiqd. Zaimportowana wtyczka ma ten sam cykl życia co wtyczka utworzona za pomocą wiqd plugin create:

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

--privacy-url i --terms-url są wymagane tylko w pierwszym importowaniu wtyczki. Jeśli źródło pochodzi z poprzedniego elementu wiqd plugin export, metadane pełnego cyklu już je zawierają.

Important

Zaimportowany projekt obsługuje tylko część cyklu życia przeznaczoną tylko do odczytu — wiqd plugin validate, show oraz list. Nie można go jeszcze spakować, aprowizować ani udostępnić, ponieważ import nie tworzy szkieletu lokalnych plików wdrożenia wymaganych przez te kroki. Jest to śledzona luka. Aby sprawdzić aktualny stan, zobacz dokumentację referencyjną CLI wiqd. Jeśli potrzebujesz pakietu do opublikowania dzisiaj, użyj skryptu konwersji.

Konwertowanie za pomocą skryptu konwersji

Skrypt konwersji tłumaczy wtyczkę Claude'a bezpośrednio na publikowalny pakiet M365:

  1. Zainstaluj interfejs wiersza polecenia (wymaga wersji 1.1.12 lub nowszej):

    npm install -g @microsoft/m365agentstoolkit-cli
    
  2. Sprawdź wersję:

    atk --version
    
  3. Zaimportuj wtyczkę:

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

Polecenie odczytuje element .claude-plugin/plugin.json (lub .cursor-plugin/plugin.json) wtyczki, .mcp.json oraz katalog skills/, a następnie tworzy szkielety projektu zestawu narzędzi agentów zawierającego appPackage/manifest.json, umiejętności i wygenerowane ikony.

Należy dołączyć --privacy-url i --terms-url ponieważ manifesty wtyczek nie mają równoważnych pól, a manifest platformy Microsoft 365 wymaga obu.

Uwaga / Notatka

atk import openplugin lokalizuje manifest wtyczki w katalogu rozpoczynającym się kropką — .claude-plugin/plugin.json, .cursor-plugin/plugin.json lub .plugin/plugin.json — obok elementu .mcp.json. Specyfikacja Wtyczki agentów 1.0.0 umieszcza manifest na najwyższym poziomie plugin.json, a konfigurację MCP na poziomie mcp.json. Aby zaimportować wtyczkę, która jest zgodna z układem 1.0.0, przenieś jej manifest do .plugin/plugin.json i zmień nazwę mcp.json na .mcp.json.

Spakuj wynik w możliwym do przekazania pliku .zip:

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

Uwaga / Notatka

atk import openplugin generuje devPreview manifest. Przykłady manifestu w innych miejscach tego artykułu są przeznaczone dla schematu w wersji 1.28. Jeśli publikujesz za pośrednictwem kanału, który wymaga wersji 1.28, update manifestVersion i $schema w wygenerowanym appPackage/manifest.json.

Importowane elementy

Artefakt wtyczki Odpowiednik M365 Notes
.claude-plugin/plugin.json manifest.json Mapowane pola nazwy, opisu i dewelopera; Identyfikator GUID wygenerowany automatycznie (deterministyczny identyfikator UUID v5)
skills/*/SKILL.md agentSkills[] wpisy + skills/ folder Skopiowano dosłownie — identyczny format
.mcp.json serwery agentConnectors[] wpisy Wykryto automatycznie adres URL i typ uwierzytelniania
color.png / outline.png Ikony w pakiecie Używane, jeśli występują; brakujące symbole zastępcze są generowane

Important

Dla każdego łącznika zaimportowanego z .mcp.json, wygenerowany element authorization.referenceId jest symbolem zastępczym pochodzącym z wtyczki i nazwy serwera. Przed opublikowaniem zastąp go swoim rzeczywistym identyfikatorem rejestracji klienta OAuth. Dowiedz się więcej w temacie Obsługiwane typy uwierzytelniania.

Elementy niekonwertowane

Następujące funkcje wtyczki Claude nie są jeszcze obsługiwane w manifeście platformy Microsoft 365:

Funkcja wtyczki Claude Status
commands/ (polecenia ukośnika) Jeszcze nie jest obsługiwane
agents/ (podagenci) Jeszcze nie jest obsługiwane
hooks/ (procedury obsługi zdarzeń) Jeszcze nie jest obsługiwane
settings.json Nie dotyczy
bin/ (pliki wykonywalne) Nie dotyczy

Opcje importu

Option Description
--path, -p Required. Katalog wtyczki zawierający .claude-plugin/plugin.json, .cursor-plugin/plugin.json, lub .plugin/plugin.json
--output, -o Docelowy folder projektu (domyślnie) ./<plugin-name>
--privacy-url developer.privacyUrl dla wygenerowanego manifestu
--terms-url developer.termsOfUseUrl dla wygenerowanego manifestu
--website-url developer.websiteUrl. Przechodzi awaryjnie do homepage, a następnie author.url
--app-id Zastąp deterministyczny identyfikator UUID v5 wygenerowany dla manifestu id
--default-auth-type Auto (ustawienie domyślne), None, OAuthPluginVaultlub ApiKeyPluginVault

Automatyczne wykrywanie typu uwierzytelniania:

Source Domyślny typ uwierzytelniania Reason
Zewnętrzne adresy URL HTTPS OAuthPluginVault Większość zdalnych interfejsów API wymaga uwierzytelniania
localhost i adresy URL bez HTTPS None Lokalne serwery programistyczne

Jeśli automatyczne wykrywanie nie odpowiada konfiguracji, użyj elementu --default-auth-type, aby ręcznie je nadpisać.

Eksportowanie z powrotem do katalogu wtyczek

Aby przenieść projekt zestawu narzędzi Agents Toolkit z powrotem do katalogu wtyczek — na przykład w celu zachowania synchronizacji wtyczki Claude Code i pakietu Cowork — użyjatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin
Option Description
--path, -p Required. Folder projektu zestawu narzędzi agentów zawierający appPackage/manifest.json
--output, -o Docelowy katalog wtyczek (domyślnie: ./<plugin-name>-openplugin)
--manifest-kind open-plugin (ustawienie domyślne, zapisuje .plugin/plugin.json), claude-plugin lub cursor-plugin

Eksport zapisuje x-microsoft-365-agents-toolkit blok do wygenerowanego plugin.jsonpliku . Ten blok zawiera id manifest, adresy URL deweloperów i ustawienia łącznika, więc późniejsze polecenie atk import openplugin wykonuje pełen cykl bez konieczności ponownego użycia elementu --privacy-url lub --terms-url.

Uwaga / Notatka

Blok x-microsoft-365-agents-toolkit jest specyficzny dla zestawu narzędzi agentów, a domyślny rodzaj open-plugin zapisuje manifest do .plugin/plugin.json. Wtyczki agentów w wersji 1.0.0 używają najwyższego poziomu plugin.json i zawierają dane specyficzne dla klienta w kluczu extensions z przestrzenią nazw odwrotnej domeny, więc inni klienci ignorują ten blok, zamiast podejmować na jego podstawie działania. Gdy obiektem docelowym jest Claude Code lub Cursor, użyj --manifest-kind claude-plugin lub cursor-plugin.

Starsza wersja: skrypt konwersji programu PowerShell

Przed obsługiwanym importem wtyczek atk konwersja używała skryptu programu PowerShell tylko dla systemu Windows, który pozostaje dostępny jako skrypt konwersji:

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

Użyj atk import openplugin zamiast tego. Jest to rozwiązanie wieloplatformowe, obsługuje źródła kodu Cursor i Claude Code, a także może eksportować z powrotem do katalogu wtyczek.

Ręczne kompletowanie pakietu

Ta sekcja jest odniesieniem do formatu pakietu: opisuje dokładnie, co Build a plugin with wiqd generuje, pole po polu. Postępuj zgodnie z tym pomysłem, gdy nie możesz zainstalować narzędzi lub tworzysz własny potok pakowania. Użyj go jako odniesienia, gdy musisz zrozumieć lub debugować wygenerowany pakiet.

Krok 1. Utwórz pierwszą umiejętność

Umiejętność to folder zawierający plik SKILL.md. Utwórz następującą strukturę folderów:

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

Napisz SKILL.md za pomocą frontmatter YAML i treści Markdown:

---
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 |

Pola frontmatter w pliku SKILL.md

Wymagane pola:

Pole Constraints Description
name 1-64 znaki, kebab-case Identyfikator umiejętności — musi dokładnie odpowiadać nazwie folderu
description 1–1024 znaki Kiedy używać tej umiejętności - dołącz frazy wyzwalające

Important

  • Nazwa folderu musi być zgodna z polem name we frontmatter. To niedopasowanie jest najczęstszą przyczyną niepowodzeń działania umiejętności.
  • Pola description z listą wtyczek nie powinny zawierać wezwań do działania kierujących użytkowników do zewnętrznych platform handlowych w celu zakupu subskrypcji.
Ścieżka folderu name pole Prawidłowe? Dlaczego
skills/contract-analysis/SKILL.md contract-analysis Yes Folder i nazwa są zgodne
skills/contract-analysis/SKILL.md ContractAnalysis No W nazwie jest używany PascalCase zamiast pasującego folderu
skills/my-skill/SKILL.md contract-analysis No Folder jest my-skill , ale nazwa jest contract-analysis

Reguły nazewnictwa (kebab-case): Używaj tylko małych znaków alfanumerycznych i myślników. Nie używaj myślników następujących po sobie. Nie używaj myślników wiodących ani końcowych.

Example Prawidłowe? Problematyka
bond-relative-value Yes Małe litery z łącznikami
fx-carry-trade Yes Małe litery z łącznikami
email Yes Jedno słowo, bez łączników
Bond_Relative_Value No Podkreślenia i wielkie litery
--my-skill-- No Łączniki wiodące i końcowe
my--skill No Następujące po sobie myślniki

Krok 2: Dodaj materiały referencyjne (opcjonalnie)

W przypadku złożonych umiejętności zachowaj podstawowe uproszczone informacje SKILL.md i przenieś szczegółową zawartość do katalogów podrzędnych. Te dodatkowe pliki są plikami towarzyszącymi. Umiejętność wczytuje je w razie potrzeby.

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

Limity plików towarzyszących

Każda umiejętność może zawierać maksymalnie 20 plików towarzyszących (dowolnych plików innych niż SKILL.md). Następujące limity obowiązują dla każdej umiejętności:

Limit Value
Pliki towarzyszące maksymalnie 20
Maksymalny rozmiar pliku towarzyszącego 5 MB
Maksymalny łączny rozmiar plików towarzyszących 10 MB
Limit czasu pobierania (wszystkie pliki towarzyszące) 15 sekund

Reguły plików towarzyszących

Ścieżki plików towarzyszących muszą być zgodne z następującymi regułami:

  • Używaj tylko ścieżek względnych (bez ścieżek bezwzględnych).
  • Brak przechodzenia po ścieżkach (segmenty: ..).
  • Nazwy plików nie mogą zawierać znaków ukośnika odwrotnego ani bajtów zerowych.
  • Brak ukrytych plików (nazwy zaczynające się od .).
  • Brak nazw zarezerwowanych systemu Windows (CON, PRN, COM1, AUX, NUL–LPT1, COM9–LPT9).
  • Sam plik SKILL.md nie jest liczony jako plik towarzyszący.
  • W nazwach plików należy używać bezpiecznych znaków: alfanumerycznych, łączników, podkreśleń, kropek, spacji i znaków !.

Aby okno kontekstowe działało wydajnie, system ładuje umiejętności w trzech warstwach:

Warstwa Po załadowaniu Rozmiar docelowy
Frontmatter (name + description) Zawsze — podczas uruchamiania Ok. 100 tokenów
SKILL.md body Po wyzwoleniu umiejętności Mniej niż 5000 tokenów (1500–2000 słów)
Odwołania (references/) Na żądanie agenta Unlimited
Skrypty (scripts/) Wykonano, nie załadowano do kontekstu N/A

Jawnie wskaż podkatalogi w SKILL.md, aby agent wiedział, że istnieją:

## 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

Krok 3. Dodaj łącznik (opcjonalnie)

Jeśli rozszerzenie wymaga dostępu do danych zewnętrznych, dodaj zdalny serwer MCP. Ten krok jest opcjonalny. Pakiety zawierające wyłącznie umiejętności dobrze sprawdzają się w przepływach pracy opartych na poleceniach.

Wskazówka

Jeśli serwer ogranicza widoczność narzędzia na podstawie klienta lub przypisuje atrybuty ruchowi przychodzącemu, zapoznaj się z tematem Identyfikowanie ruchu Cowork na serwerze, aby uzyskać szczegółowe informacje o tożsamości klienta prezentowanej przez Cowork.

Uwaga / Notatka

Wtyczki niestandardowe nie są obsługiwane w aplikacji Cowork na urządzenia przenośne.

Wymagania dotyczące łącznika

Requirement Details
Transport Protokół HTTP z obsługą przesyłania strumieniowego (wymagany protokół HTTPS, TLS 1.2+)
Protocol Format wiadomości JSON-RPC 2.0
Odnajdywanie narzędzi Obsługa tools/list dynamicznego wykrywania (zalecane)
Uruchamianie narzędzia Obsługa elementu tools/call na potrzeby wywołania
Availability Zalecana umowa SLA dotycząca czasu działania na poziomie 99,9% dla aplikacji opublikowanych w sklepie
Czas odpowiedzi Mniej niż 30 sekund na wywołanie narzędzia

Wskazówki dotyczące projektowania narzędzi

  • Jedno narzędzie na akcję dla małych interfejsów API (mniej niż 15 operacji): search_case_law, get_ruling, cite_precedent
  • Wyszukaj i wykonaj dla dużych interfejsów API (50+ operacji): search_actions + execute_action
  • Nazwy opisowe: get_bond_price nie getData
  • Rozbudowane schematy wejściowe: dołącz opis dla każdego parametru — to właśnie odczytuje agent
  • Dane wyjściowe ze strukturą: zwraca dane JSON, które agent może sformatować dla użytkownika
  • Dane wejściowe pliku: Aby zaakceptować plik z obszaru roboczego użytkownika, zadeklaruj parametr za pomocą contentEncoding: base64. Dowiedz się więcej w artykule Akceptowanie plików z obszaru roboczego Cowork.

Opisz narzędzia łącznika (mcpToolDescription)

Łącznik remoteMcpServer może opcjonalnie zawierać mcpToolDescription obiekt. Po podaniu jego zagnieżdżona właściwość file wskazuje plik JSON z opisem narzędzia, który pakujesz wewnątrz .zip i do którego odwołujesz się za pomocą ścieżki względnej od katalogu głównego pakietu. Aplikacja Cowork dynamicznie wykrywa narzędzia z serwera MCP i nie używa tego pliku, nawet jeśli jest obecny.

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

Jeśli dołączysz mcpToolDescription, plik, do którego prowadzi odwołanie (na przykład tools/contoso-legal-tools.json), opisuje narzędzia udostępniane przez łącznik i musi znajdować się w pakiecie ZIP. Dołącz go wraz z folderami manifest.json i skills/ podczas pakowania wtyczki.

Wskazówka

To wymaganie dotyczy wersji manifestu 1.28. Pakiety generowane przez polecenie wiqd plugin create są przeznaczone dla wersji 1.29, w której wpisy agentConnectors[] są tylko adresami URL, opis mcpToolDescription jest opcjonalny i nie ma pliku opisu narzędzia do zapomnienia.

Obsługiwane typy uwierzytelniania

Typ uwierzytelniania Kiedy stosować Doświadczenie użytkownika
None Publiczne lub anonimowe interfejsy API, usługi wewnętrzne Przejrzyste — brak monitu o uwierzytelnienie
OAuthPluginVault Interfejsy API OAuth 2.0 (zalecane w środowisku produkcyjnym) Użytkownik jeden raz wyraża zgodę na OAuth
ApiKeyPluginVault Usługi oparte na kluczach API Użytkownik podaje klucz raz

Uwaga / Notatka

  • Obsługa uwierzytelniania kluczem API nie jest jeszcze dostępna w usłudze Cowork.
  • Jeśli serwer MCP wymaga klucza interfejsu API, użyj w zamian elementu OAuthPluginVault lub dynamicznej rejestracji klienta albo udostępnij punkt końcowy, który akceptuje opcję None.

Wzorzec referencyjny łączący aplikację Cowork z usługą chronioną za pomocą klucza interfejsu API można znaleźć za pośrednictwem punktu końcowego MCP chronionego przez firmę Entra w temacie Tworzenie wtyczki dla interfejsu API biznesowego.

Dla OAuthPluginVault i ApiKeyPluginVault element referenceId wskazuje na poświadczenia przechowywane w magazynie tokenów przedsiębiorstwa Microsoft — sekrety nigdy nie pojawiają się w pliku manifestu ani w plikach umiejętności. Wartość referenceId jest identyfikatorem rejestracji klienta OAuth tworzonym podczas rejestrowania klienta OAuth w zestawie narzędzi Agents Toolkit.

Important

Podczas rejestrowania klienta OAuth ustaw użycie według organizacji na dowolną organizację platformy Microsoft 365, aby upewnić się, że wtyczka działa w różnych dzierżawach.

Uwierzytelnianie MCP

Aby używać uwierzytelniania OAuth lub ApiKey, zobacz Konfigurowanie uwierzytelniania dla wtyczek protokołu MCP i API w agentach w funkcji Microsoft 365 Copilot, aby uzyskać szczegółowe informacje na temat konfiguracji i konfiguracji.

Dynamiczna rejestracja klienta

Jeśli serwer MCP obsługuje dynamiczną rejestrację klienta (DCR, Dynamic Client Registration), możesz pominąć konfigurację authentication w definicji łącznika, a rozwiązanie Cowork automatycznie utworzy klienta OAuth w imieniu Twojej wtyczki.

Uwaga / Notatka

Pominięcie authentication konfiguracji jest obsługiwane tylko w usłudze Cowork. Nie jest to obsługiwane w usłudze Copilot Chat. Jeśli wtyczka musi również działać w funkcji Copilot Chat, skonfiguruj OAuthPluginVault uwierzytelnianie zgodnie z opisem w sekcji Obsługiwane typy uwierzytelniania.

Obiekt authorization można całkowicie pominąć. Skonfiguruj adres URL serwera MCP, a usługa Cowork zajmie się klientem OAuth:

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

Krok 4. Utwórz manifest

Utwórz plik manifest.json w katalogu głównym pakietu. W przykładzie użyto manifestu w wersji 1.28; polecenie wiqd plugin create wskazuje wersję 1.29, gdzie wpisy łączników są tylko adresami URL.

{
  "$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" }
  ]
}

Aby dodać łącznik, uwzględnij następujące łączniki 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"
          }
        }
      }
    }
  ]
}

W konfiguracji łącznika referenceId powinien znajdować się identyfikator rejestracji OAuth. Jeśli dołączysz opis mcpToolDescription, jego element file musi wskazywać plik JSON z opisem narzędzia, który znajduje się w pakiecie ZIP.

Important

Schemat manifestu w wersji 1.28 jest rygorystyczny: ustawia parametr additionalProperties: false na poziomie głównym, więc każde pole niezdefiniowane w schemacie jest odrzucane. Pola, które są prawidłowe w standardowych manifestach aplikacji Teams — takie jak packageName — powodują niepowodzenie przekazywania z błędem, takim jak Property 'packageName' has not been defined and the schema does not allow additional properties. Uwzględnij tylko pola pokazane tutaj.

Krok 5. Dodaj ikony

Utwórz dwie ikony PNG:

Icon Size Purpose
color.png 192×192 px Pełnokolorowa ikona aplikacji wyświetlana w sklepie i na liście aplikacji
outline.png 32×32 pikseli Jednokolorowa ikona konturu w widokach kompaktowych

Jeśli nie masz jeszcze ikon, atk import openplugin generuje symbole zastępcze w jednolitym kolorze. Wymień je przed przesłaniem do sklepu.

Krok 6. Pakiet

Utwórz plik ZIP z całą zawartością na poziomie głównym. wiqd plugin package( wytwarza tę samą strukturę po wiqd plugin provision.)

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

Jeśli łącznik zawiera mcpToolDescription, dołącz plik JSON z opisem narzędzia, do którego się odwołuje. Pakiety, które nie używają mcpToolDescription, w tym pakiety tylko umiejętności, nie potrzebują folderu 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/

Korzystanie z zestawu narzędzi Microsoft 365 Agents Toolkit

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

Krok 7. Test

Aby przetestować aplikację, prześlij pakiet aplikacji do usługi Teams zgodnie z opisem w temacie Przekazywanie aplikacji do usługi Teams.

Jeśli wtyczka została utworzona za pomocą narzędzia wiqd, zamiast tego uruchom polecenie wiqd plugin provision — powoduje ono zarejestrowanie wtyczki w dzierżawie. Na potrzeby osobistego testowania ręcznie utworzonego pakietu załaduj bezpośrednio aplikację przy użyciu interfejsu wiersza polecenia zestawu narzędzi agentów platformy Microsoft 365:

  1. Zainstaluj @microsoft/m365agentstoolkit-cli z npm:

    npm install -g @microsoft/m365agentstoolkit-cli
    
  2. Sprawdź instalację, uruchamiając polecenie:

    atk --version
    
  3. Uwierzytelnij się przy użyciu konta służbowego platformy Microsoft 365:

    atk auth login
    
  4. Zaloguj się do konta firmowego i zainstaluj pakiet agenta. Zastąp ścieżkę pliku lokalizacją pakietu ZIP:

    atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
    

    Pomyślna instalacja zwraca dane wyjściowe, które zawierają elementy TitleId i AppId Twojego konta.

  5. Zapisz te identyfikatory do późniejszego użycia podczas aktualizowania lub odinstalowywania.

Dowiedz się więcej w temacie Interfejs wiersza polecenia zestawu narzędzi agentów platformy Microsoft 365.

Krok 8. Opublikuj w dzierżawcy

Przekaż pakiet do centrum administracyjnego, aby dodać wtyczkę do listy w sekcji Odkryj, gdzie każda osoba w Twojej organizacji może ją znaleźć:

  1. Otwórz obszar Centrum administracyjne platformy M365>Zarządzaj aplikacjami>Przekaż aplikację niestandardową.
  2. Wybierz przycisk wielokropka (...) >Dodaj agenta.
  3. Przekaż pakiet .zip.
  4. Otwórz obszar Cowork>Źródła & umiejętności>Wtyczki. Twoja wtyczka pojawi się w sekcji Odkryj .

wiqd plugin share umieszcza wtyczkę w obszarze Udostępnione dla mnie, a nie Discover. Użyj jej do testowania i ukierunkowanego wdrażania dla określonych osób. Przekazanie w centrum administracyjnym powoduje wyświetlenie wtyczki do wykrycia.

Krok 9. Opublikuj publicznie

W przypadku wtyczek przeznaczonych do dystrybucji publicznej przekaż wtyczkę do sklepu z aplikacjami na platformie Microsoft 365 za pośrednictwem Centrum partnerskiego. Dowiedz się więcej w artykule Publikowanie agentów dla usługi Microsoft 365 Copilot.

Przetestuj łącznik względem lokalnego serwera MCP

Łączniki wymagają adresu mcpServerUrl protokołu HTTPS. Aby przetestować serwer działający na komputerze, musisz udostępnić go za pośrednictwem publicznego adresu URL HTTPS. Tunele deweloperskie udostępniają przekaźnik, który obsługuje terminację TLS.

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

Important

Użyj --protocol http, a nie https. Flaga --protocol opisuje usługę lokalną, do której tunel przekazuje, a nie publiczny adres URL tunelu. Większość lokalnych serwerów MCP używa zwykłego protokołu HTTP, więc jeśli ustawisz --protocol https, gdy Twój serwer obsługuje protokół HTTP, każde żądanie przesyłane przez tunel zwróci błąd 502. Przekazanie kończy działanie protokołu TLS i obsługuje publiczny adres URL za pośrednictwem protokołu HTTPS bez względu na tę flagę.

Troubleshooting

Objaw Przyczyna Napraw.
Każde żądanie przesyłane przez tunel zwraca błąd 502, a serwer lokalny odczytuje protokół HTTP devtunnel port create polecenie zostało uruchomione za pomocą polecenia --protocol https Odtwórz port za pomocą polecenia --protocol http
Żądania w tunelu zwracają błąd 502 w systemie macOS, mimo że serwer lokalny działa Serwer jest powiązany z adresem 0.0.0.0 (tylko IPv4), ale tunel łączy się z localhost, który wskazuje najpierw na adres ::1 (IPv6) Powiąż serwer tak, aby funkcja :: akceptowała połączenia IPv4 i IPv6
Przekazywanie kończy się niepowodzeniem, błąd Property '<field>' has not been defined and the schema does not allow additional properties Manifest zawiera pole, na które schemat w wersji 1.28 nie zezwala (na przykład packageName) Usuń pole; schemat w wersji 1.28 używa additionalProperties: false

Wzory opakowań

Wybierz wzorzec, który pasuje do rozszerzenia:

Tylko umiejętności (bez łącznika)

Najlepsza opcja w przypadku przepływów pracy opartych na poleceniach, analizy dokumentów i pomocy podczas pisania.

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

Umiejętności + łącznik zdalny

Najlepsze do analizy danych, integracji API i systemów korporacyjnych.

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

Tylko łącznik (brak umiejętności niestandardowych)

Użyj tej opcji dla źródeł danych, z których wbudowane umiejętności usługi Cowork mogą już korzystać.

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

Zaimportowana wtyczka kodu lub kursora modelu Claude

Użyj tej opcji dla istniejących wtyczek ekosystemu Claude przeznaczonych dla usługi Cowork. Aby dalej rozwijać wtyczkę na platformie Microsoft 365, zaimportuj ją:

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

Aby utworzyć plik .zip z możliwością publikacji z poziomu wtyczki w jej obecnym kształcie, użyj skryptu konwersji:

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

Najlepsze rozwiązania dotyczące tworzenia umiejętności

Postępuj zgodnie z tymi wskazówkami, aby tworzyć skills, które aktywują się niezawodnie i dają spójne wyniki.

Twórz efektywne opisy

Pole description określa, kiedy agent aktywuje umiejętność. Podawaj konkretne informacje:

# 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.

Pisz skuteczne przepływy pracy

  • Opis powinien być konkretny. Uwzględnij frazy wyzwalające: "Użyj, gdy użytkownik prosi o..." Ten opis pokazuje, w jaki sposób agent decyduje, którą umiejętność aktywować.
  • Przedstaw to jako przepływ pracy. Ponumeruj kroki. Każdy krok powinien odpowiadać konkretnej akcji (odczyt pliku, wywołanie narzędzia, generowanie danych wyjściowych).
  • Zdefiniuj format wyjściowy. Pokaż dokładną strukturę tabeli, listy lub dokumentu, jakiej oczekują użytkownicy. Ta definicja znacznie poprawia spójność.
  • Odwołuj się do narzędzi po nazwie. Jeśli umiejętność zależy od narzędzi łącznika, podaj wyraźnie jej nazwę: „Użyj narzędzia search_case_law do...”
  • Zachowaj główny plik SKILL.md zwięzły. Przenieś szczegółowe materiały referencyjne do podkatalogu references/ . Treść umiejętności powinna być przepływem pracy, a nie encyklopedią.

Unikaj typowych błędów

  • Nie osadzaj sekretów w plikach SKILL.md. Użyj elementu agentConnectors do uwierzytelniania w przypadku poświadczeń interfejsu API.
  • Nie duplikuj wbudowanych umiejętności. Przed rozpoczęciem tworzenia sprawdź listę wbudowanych umiejętności.
  • Nie twórz zbyt ogólnych umiejętności. „Rób wszystko w dokumentach prawnych” jest gorsze niż konkretne umiejętności w zakresie „analizy kontraktów”, „wyodrębniania klauzul” i „analizy stanu prawnego”.
  • Nie zapisuj na stałe ścieżek plików ani poleceń systemowych. Umiejętności powinny być przenośne między środowiskami.
  • Nie umieszczaj wszystkiego w SKILL.md. Jeśli treść główna przekracza ok. 3000 słów, przenieś szczegółową zawartość do folderu references/.

Reguły walidacji

Po przesłaniu pakietu platforma weryfikuje go na wielu poziomach. Popraw te błędy przed wysłaniem, aby uniknąć odrzucenia zgłoszenia.

Aby przechwytywać je podczas kompilacji, a nie w czasie przesyłania, uruchom polecenie wiqd plugin validate --mode deep. To polecenie pakuje wtyczkę i uruchamia te same reguły lokalnie. Dowiedz się więcej w Krok 3: Weryfikacja podczas tworzenia.

Sprawdzanie poprawności na poziomie manifestu

Code Rule Severity
ASKILL-M001 folder jest wymagany dla każdego wpisu agentSkills Error
ASKILL-M002 agentSkills tablica może zawierać maksymalnie 20 elementów Error
ASKILL-M003 folder ścieżka może mieć maksymalnie 256 znaków Error

Sprawdzanie poprawności na poziomie pakietu

Code Rule Typowa poprawka Severity
ASKILL-P001 Folder, do którego odwołuje się manifest, istnieje w pliku ZIP Sprawdź strukturę pliku ZIP Error
ASKILL-P002 Folder zawiera plik SKILL.md Dodaj brakujące SKILL.md Error
ASKILL-P003 SKILL.md ma prawidłowy frontmatter YAML między ogranicznikami --- Popraw składnię YAML Error
ASKILL-P004 Sekcja frontmatter zawiera pole name Dodaj element name: do sekcji frontmatter Error
ASKILL-P005 Sekcja frontmatter zawiera pole description Dodaj element description: do sekcji frontmatter Error
ASKILL-P006 name pasuje do nazwy folderu (ostatni segment ścieżki) Zmień nazwę folderu lub popraw name: Error
ASKILL-P007 name jest kebab-case Użyj elementu my-skill, nie MySkill lub my_skill Error
ASKILL-P008 Brak powtarzających się wartości folder w tablicy Usuwanie duplikatów Error

Walidacja łącznika

Rule Severity
Każdy łącznik wymaga id oraz displayName Error
Wszystkie wartości łączników id muszą być unikatowe w manifeście Error
Dokładnie jeden z plugin lub remoteMcpServer Error
mcpServerUrl musi być prawidłowym adresem URL HTTPS Error
Jeśli istnieje opis mcpToolDescription, jego file musi istnieć w pliku ZIP Error
authorization.referenceId wymagane, chyba że typ jest None Error
authorization.referenceId nie może być obecny, gdy typ jest None Error

Walidacja pliku towarzyszącego

Portal weryfikuje pliki towarzyszące (materiały referencyjne, skrypty i inne pliki obok SKILL.md) podczas przekazywania i synchronizacji:

Rule Severity
Maksymalnie 20 plików towarzyszących na jedną umiejętność (z wyłączeniem SKILL.md) Error
Każdy plik towarzyszący musi mieć rozmiar nie większy niż 5 MB Error
Łączna ilość plików towarzyszących na umiejętność nie może przekraczać 10 MB Error
Ścieżki plików muszą być względne (nie mogą być ścieżkami bezwzględnymi) Error
Brak segmentów przechodzenia po ścieżkach (..) Error
Nazwy plików nie mogą zawierać ukośników odwrotnych ani bajtów null Error
Brak ukrytych plików (nazwy zaczynające się od .) Error
Brak nazw zarezerwowanych w systemie Windows (CON, PRN, COM1, AUX, NUL–LPT1, COM9–LPT9) Error
W nazwach plików należy używać wyłącznie bezpiecznych znaków (znaków alfanumerycznych, łączników, podkreśleń, kropek, spacji, !) Error

Zgodność międzyplatformowa

Umiejętności korzystają z otwartego standardu Agent Skills. Te same SKILL.md pliki działają w wielu narzędziach AI:

Platform Compatibility
Kod Claude'a Dokładnie ten sam format SKILL.md
Projekty Claude.ai Full-skills można przesłać jako pliki projektu
VS Code/GitHub Copilot Umiejętności pełnego agenta obsługiwane w trybie agenta
Gemini CLI Obsługiwane umiejętności pełnego agenta
JetBrains Junie Obsługiwane umiejętności pełnego agenta
Kodeks OpenAI Obsługiwane umiejętności pełnego agenta
Cursor Obsługiwane umiejętności pełnego agenta

Jeśli rozwijasz umiejętności dla rozwiązań Claude Code i Copilot Cowork, utwórz wtyczkę za pomocą interfejsu wiqd. Następnie uruchom wiqd plugin export --format claude-plugin, aby utworzyć układ Claude Code. Jeśli wolisz zacząć od struktury wtyczki Claude Code - jest to nadzbiór - układ jest następujący:

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)

Następnie wprowadź go do platformy Microsoft 365, gdy wszystko będzie gotowe do opublikowania w sklepie Microsoft 365 App Store, za pomocą wiqd plugin import lub za pomocą skryptu konwersji:

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

Zarządzanie adnotacjami i potwierdzeniami MCP

Rozwiązanie Copilot Cowork odczytuje standardowy obiekt annotations MCP na narzędziach, które serwer zwraca z folderu tools/list, i używa go do decydowania, czy wywołanie narzędzia wymaga potwierdzenia użytkownika i jaka etykieta ma być wyświetlana w poleceniu.

Dostępne pola

Pole Typ Efekt
readOnlyHint bool false: potwierdzenie wymagane przed uruchomieniem narzędzia.
destructiveHint bool true: potwierdzenie wymagane przed uruchomieniem narzędzia.
title ciąg Czytelna dla człowieka etykieta wyświetlana w oknie dialogowym potwierdzenia. Używa awaryjnie nazwy narzędzia w przypadku braku wartości.

Reguły potwierdzania

Potwierdzenie jest wymagane, jeśli readOnlyHint == false lub destructiveHint == true.

Wszystkie narzędzia muszą mieć określone adnotacje dotyczące bezpieczeństwa. Narzędzia bez adnotacji są traktowane jako destrukcyjne i wymagają potwierdzenia. Więcej informacji znajdziesz w dokumentacji schematu MCP.

Przykłady MCP

Destrukcyjne działanie z przyjazną etykietą:

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

Bezpieczny odczyt, który uruchamia się automatycznie:

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

Co jest obecnie dostępne

  • Narzędzia Microsoft (Graph, Dataverse i inne) podlegają wbudowanym zasadom usługi Cowork niezależnie od adnotacji.
  • W przypadku serwerów MCP firm innych niż Microsoft potwierdzenie oparte na adnotacjach jest wdrażane stopniowo. Ustawienie wskazówek już teraz jest zgodne z przyszłymi zmianami, a polecenia dotyczące potwierdzenia są wyświetlane w miarę rozszerzania wdrożenia bez konieczności wprowadzania zmian deweloperskich.

Akceptuj pliki z przestrzeni roboczej Cowork

Narzędzie łącznika może pobrać plik z sesji Cowork użytkownika jako dane wejściowe — dokument dołączony przez użytkownika, załącznik wiadomości e-mail zapisany przez usługę Cowork lub plik utworzony we wcześniejszym kroku. Zadeklaruj parametr za pomocą standardowego słowa kluczowego JSON Schema contentEncoding: base64, a usługa Cowork zajmie się resztą. Nie jest wymagane żadne rozszerzenie schematu specyficzne dla firmy Microsoft, a powierzchnia interfejsu API serwera nie ulega zmianie.

Cowork odnajduje plik obszaru roboczego i koduje go w base64 przed wywołaniem serwera, więc bajty pliku nigdy nie wchodzą do kontekstu agenta. Agent widzi i emituje tylko ścieżki plików obszaru roboczego.

Uwaga / Notatka

Nie instruuj agenta, aby sam kodował plik w standardzie base64 i wklejał obiekt blob do wywołania narzędzia. Takie podejście ładuje cały plik do kontekstu modelu i opiera się na tym, że model dokładnie odtworzy obiekt blob. Wygląda na to, że działa na małych plikach testowych, a zawodzi na rzeczywistych plikach.

Deklarowanie parametru pliku

Właściwość ciągu z parametrem contentEncoding: base64 jest rozpoznawana jako dane wejściowe pliku:

{
  "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"]
  }
}

Tablica takich ciągów jest także rozpoznawana przez narzędzia, które akceptują kilka plików:

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

Co widzi agent

W przypadku parametrów pliku zadeklarowanych na najwyższym poziomie inputSchema.properties, Cowork zastępuje je w schemacie modelowym pojedynczą direct_attachment_file_paths tablicą - tym samym parametrem używanym przez wbudowane narzędzia Cowork, więc agent już wie, jak go wypełnić. Powyższy schemat jest przedstawiany agentowi jako:

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

Jeśli narzędzie zadeklaruje więcej niż jeden parametr pliku najwyższego poziomu, wszystkie z nich zostaną zwinięte do tej pojedynczej direct_attachment_file_paths tablicy. W momencie wywołania usługa Cowork przypisuje zwrócone pliki z powrotem do oryginalnych nazw parametrów w kolejności deklaracji.

Parametry pliku zagnieżdżonego

Agent obsługuje parametr pliku zagnieżdżony wewnątrz obiektu lub tablicy obiektów. Agent obsługuje ten parametr inaczej: zamiast go zwijać, agent przepisuje go w miejscu jako ciąg znaków ścieżki w tej samej lokalizacji. Takie podejście zachowuje skojarzenie między plikiem i powiązanym z nim polami. Na przykład otrzymujesz jeden paragon dla każdego wiersza wydatku:

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

Agent wypełnia obszar line_items[].receipt ścieżką obszaru roboczego, a usługa Cowork zamienia każdą ścieżkę zawartością base64 w miejscu przed przekazaniem połączenia.

Zagnieżdżenie jest przeszukiwane do głębokości czterech poziomów poniżej szczytu elementu inputSchema. $ref Odwołania nie są śledzone — zdefiniuj parametry pliku w tekście, a nie poprzez element $ref.

Co odbiera Twój serwer

Serwer odbiera zwykły obszar tools/call z oryginalnymi nazwami parametrów wypełnionymi zawartością zakodowaną w standardzie base64:

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

Serwer nie musi wiedzieć, że agent używał interfejsu opartego na ścieżkach, a narzędzia, które nie deklarują parametrów contentEncoding: base64, pozostają niezmienione.

Limity

Limit Value
Pliki na wywołanie narzędzia 8
Rozmiar na plik 150 MiB
Całkowity rozmiar na jedno wywołanie narzędzia 150 MiB
Parametry tablicy pliku na narzędzie 1 (połącz z dowolną liczbą skalarnych parametrów pliku)
Maksymalna głębokość zagnieżdżania 4 poziomy poniżej szczytu elementu inputSchema

Wywołanie przekraczające liczbę plików lub limit rozmiaru kończy się niepowodzeniem z powodu błędu narzędzia i nigdy nie dociera do serwera. Dopasuj rozmiar interfejsu API i jego limitów czasu, mając na uwadze pułap 150 MiB: base64 zawyża ładunek o około jedną trzecią w stosunku do pierwotnego rozmiaru pliku, a zakodowana zawartość jest wysyłana w treści żądania JSON-RPC.

Recommendations

  • Opisz parametr dla czytelnika. Agent używa opisu, aby zdecydować, który plik należy do którego parametru. Na przykład "The signed contract PDF to analyze" działa lepiej niż "file".
  • Podaj formaty akceptowane w opisie parametru. Rozwiązanie Cowork przekazuje wszystko, co użytkownik dołączy. Zweryfikuj typ zawartości po swojej stronie, a jeśli nie nadaje się do użytku, zwróć czytelny komunikat błędu narzędzia.
  • Ustaw adnotacje. Narzędzie, które odbiera plik i pracuje na nim, zwykle nie jest tylko do odczytu, dlatego monituje o potwierdzenie. Dowiedz się więcej na temat zarządzania adnotacjami i potwierdzeniami MCP.
  • Zachowaj śródwierszowe parametry pliku. Parametr znajdujący się za elementem $reflub zagnieżdżony głębiej niż cztery poziomy nie jest pisany ponownie. Serwer otrzyma ciąg ścieżki w miejscu, w którym oczekuje zawartości.
  • Zadeklaruj co najwyżej jeden parametr pliku tablicy na narzędzie. W przypadku co najmniej dwóch plików rozwiązanie Cowork nie może określić, który plik należy do której tablicy, a wywołanie kończy się niepowodzeniem z powodu błędu narzędzia. Użyj jednej tablicy, kilku parametrów skalarnych lub kombinacji skalarów i pojedynczej tablicy.
  • Spodziewaj się dokładnej liczby w narzędziach obsługujących tylko parametry skalarne. Jeśli narzędzie deklaruje tylko skalarne parametry pliku, liczba plików przekazywanych przez agenta musi być zgodna z liczbą zadeklarowaną. Wyraźnie oznacz opcjonalne parametry pliku w opisach, aby agent nie podał ich za mało ani za dużo.

Uwaga / Notatka

Mechanizm ten poprzedza prace nad danymi wejściowymi plików w protokole kontekstu modelu, które są standaryzowane przez grupę roboczą obsługującą przekazywanie plików MCP. Rozwiązanie Cowork może dodać obsługę standaryzowanego formularza deklaratywnych danych wejściowych pliku po jego odebraniu. Opisana contentEncoding: base64 tutaj umowa nadal obowiązuje.

Identyfikowanie ruchu rozwiązania Cowork do serwera

Jeśli Twój serwer MCP kontroluje widoczność narzędzi w zależności od klienta lub chcesz przypisać ruch, który otrzymuje, możesz rozpoznać żądania pochodzące z usługi Cowork. Usługa Cowork prezentuje stabilną tożsamość oprogramowania w dwóch kanałach:

Channel Gdzie występuje Value
User-Agent nagłówek żądania Każde żądanie wychodzące, które usługa Cowork wysyła do Twojego serwera copilot-cowork/1.0
clientInfo podczas uzgadniania MCP initialize Tylko żądanie initialize { "name": "copilot-cowork", "version": "<version>" }

Dopasuj według prefiksu copilot-cowork

Dopasuj copilot-coworkprefiks bez uwzględniania wielkości liter na dowolnym z kanałów. Nie dopasowuj dokładnie tego ciągu copilot-cowork/1.0 ani określonego clientInfo.version. Wersja śledzi kontrakt tożsamości klienta i oczekuje się, że ulegnie zmianie; dopasowanie prefiksu zapewnia zgodność bramy przy zmianach wersji.

# Correct: case-insensitive prefix match
copilot-cowork

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

Wybierz odpowiedni kanał bramy

Dwa kanały mają różne zakresy, więc wybierz ten, który odpowiada sposobowi, w jaki serwer wymusza użycie tej bramki:

  • Nagłówek User-Agent jest obecny w każdym żądaniu, w tym tools/list i tools/call. Jeśli stosujesz ograniczenia lub przypisujesz użycie na żądanie, używaj tego nagłówka jako klucza.
  • clientInfo jest wysyłany tylko podczas initialize uzgadniania połączenia. Jeśli stosujesz ograniczenia na sesję w czasie połączenia, można je tam odczytać, ale nie są powtarzane przy późniejszych żądaniach.

Co obejmuje i czego nie zawiera tożsamość

Tożsamość nazywa tylko oprogramowanie. Wartość jest taka sama dla każdego użytkownika i połączenia rozwiązania Cowork, a tożsamość użytkownika nie jest przenoszona. Tożsamość użytkownika pozostaje w ramach przepływu autoryzacji, który definiuje konfiguracja uwierzytelniania Twojego łącznika.

Tożsamość obejmuje Tożsamość nie obejmuje
Stabilna nazwa oprogramowania (copilot-cowork) i wersja umowy Identyfikator dowolnego dzierżawcy, użytkownika, sesji lub konwersacji
Ta sama wartość dla każdego żądania i dla każdego połączenia Kwalifikator na łącznik

Ponieważ nie ma kwalifikatora na łącznik, obecnie nie można użyć tej tożsamości do określenia, który łącznik wykonał połączenie, ani do oddzielenia opublikowanej wtyczki Microsoft od serwera dołączonego ręcznie, który wskazuje ten sam adres URL. Jeśli potrzebujesz takiego rozróżnienia, wymuś je poprzez konfigurację autoryzacji łącznika, a nie tożsamość klienta.

Często zadawane pytania

Czy mogę używać umiejętności z pakietu M365 w programie Claude Code?

Yes. Foldery umiejętności zawierają standardowe umiejętności agenta. Uruchom wiqd plugin export --format claude-plugin w celu utworzenia układu Claude Code lub skopiuj foldery skilli do .claude/skills/ w dowolnym projekcie Claude Code.

Czy potrzebuję remote connectora?

No. Pakiety zawierające wyłącznie umiejętności dobrze sprawdzają się w przepływach pracy opartych na poleceniach. Łączniki są potrzebne tylko wtedy, gdy umiejętność wymaga aktualnych danych z systemu zewnętrznego.

W jaki sposób umiejętności wtyczek różnią się od wbudowanych umiejętności?

Umiejętności wtyczki pojawiają się ze źródłem "package" w interfejsie API. Nie mogą zastąpić wbudowanych umiejętności o tej samej nazwie. Pakiety wdrożone przez administratora mają parametr isAdminDeployed: true.

Czy administratorzy IT mogą kontrolować, które wtyczki są dostępne?

Yes. Stosowane są standardowe mechanizmy kontroli administratora usługi M365: listy dozwolonych/zablokowanych na poziomie dzierżawcy, wdrożenia zarządzane przez administratora i zasady zgodności.

Co się stanie, jeśli wtyczka zostanie odwołana?

W następnym cyklu synchronizacji Skills i łączniki z tego pakietu zostaną usunięte z sesji użytkownika. Aktywne konwersacje nie są przerywane, ale nowe sesje nie mają funkcji pakietu.

Jaka jest maksymalna liczba umiejętności na pakiet?

Dwadzieścia (20) umiejętności (za ASKILL-M002). W przypadku łączników limit wynosi 10 sztuk na pakiet.

Czy umiejętności mogą odwoływać się do narzędzi łącznika z tego samego pakietu?

Tak i tak powinno być. Nadaj wyraźnie nazwy narzędziom w przepływie pracy SKILL.md (na przykład „Użyj narzędzia search_case_law do...”). Agent łączy je podczas działania.

Czy narzędzia mojej wtyczki mogą akceptować pliki z obszaru roboczego Cowork?

Yes. Zadeklaruj parametr narzędzia za pomocą contentEncoding: base64. Rozwiązanie Cowork przekształci plik obszaru roboczego użytkownika do zawartości base64 przed wywołaniem serwera. Model przekazuje ścieżki plików, a nie zawartość plików, więc duże pliki nie zużywają kontekstu modelu. Aby uzyskać szczegółowe informacje na temat deklaracji i limitów, dowiedz się więcej w temacie Akceptowanie plików z obszaru roboczego Cowork.

Jak wygenerować deterministyczny identyfikator GUID dla mojego pakietu?

wiqd plugin create generuje i przypina za Ciebie identyfikator aplikacji. Skrypt konwersji używa identyfikatora UUID v5 (opartego na algorytmie SHA-1) z nazwy wtyczki, więc dwukrotne uruchomienie konwersji daje ten sam identyfikator GUID. Do ręcznego pakowania użyj dowolnego generatora identyfikatorów GUID. Upewnij się, że rozwiązanie jest stabilne w różnych wersjach.

Którą wersję manifestu powinienem wybrać jako docelową?

Użyj wersji docelowej 1.29, jeśli kompilujesz przy użyciu interfejsu wiqd, który ją przypina w Twoim imieniu. W wersji 1.29 wpisy agentConnectors[] są tylko adresami URL, a element mcpToolDescription jest opcjonalny. W ręcznie utworzonych przykładach w tym artykule użyto wersji 1.28, w której opis mcpToolDescription jest wymagany, a plik, którego nazwę wskazuje, musi znajdować się w archiwum ZIP. atk import openplugin używa identyfikatora UUID v5 (opartego na algorytmie SHA-1) na podstawie nazwy Twojej wtyczki. Dwukrotne uruchomienie importu generuje ten sam identyfikator GUID. Aby ustawić własne, przekaż --app-id. Do ręcznego pakowania użyj dowolnego generatora identyfikatorów GUID. Upewnij się, że rozwiązanie jest stabilne w różnych wersjach.