Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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.jsonz deklaracjamiagentSkillsiagentConnectors). - 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
- Bezpośrednie udostępnianie (za pośrednictwem Work IQ Dev Tools lub
-
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.iobranż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:
Zainstaluj interfejs wiersza polecenia (wymaga wersji 1.1.12 lub nowszej):
npm install -g @microsoft/m365agentstoolkit-cliSprawdź wersję:
atk --versionZaimportuj 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
namewe frontmatter. To niedopasowanie jest najczęstszą przyczyną niepowodzeń działania umiejętności. - Pola
descriptionz 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.mdnie 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_priceniegetData - 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
OAuthPluginVaultlub 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:
Zainstaluj
@microsoft/m365agentstoolkit-cliznpm:npm install -g @microsoft/m365agentstoolkit-cliSprawdź instalację, uruchamiając polecenie:
atk --versionUwierzytelnij się przy użyciu konta służbowego platformy Microsoft 365:
atk auth loginZaloguj 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 PersonalPomyślna instalacja zwraca dane wyjściowe, które zawierają elementy
TitleIdiAppIdTwojego konta.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źć:
- Otwórz obszar Centrum administracyjne platformy M365>Zarządzaj aplikacjami>Przekaż aplikację niestandardową.
- Wybierz przycisk wielokropka (...) >Dodaj agenta.
- Przekaż pakiet
.zip. - 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_lawdo...” -
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 elementuagentConnectorsdo 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-Agentjest obecny w każdym żądaniu, w tymtools/listitools/call. Jeśli stosujesz ograniczenia lub przypisujesz użycie na żądanie, używaj tego nagłówka jako klucza. -
clientInfojest wysyłany tylko podczasinitializeuzgadniania 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.