Vytvářet pluginy pro Copilot Cowork

Microsoft Copilot Cowork podporuje rozšiřitelnost prostřednictvím balíčků aplikací M365 – stejný distribuční mechanismus, který používají aplikace Teams, agenti Copilotu a doplňky Office. Cowork můžete rozšířit o:

• Dovednosti: Pracovní postupy založené na pokynech, které učí společnost Cowork novým odborným znalostem, jako je finanční analýza, právní výzkum nebo pracovní postupy v oblasti lidských zdrojů.
• Konektory: Vzdálené servery, které umožňují Coworku přístup k externím zdrojům dat a rozhraním API.

Oba jsou součástí standardního balíčku aplikací Microsoft 365 a distribuovány prostřednictvím obchodu Microsoft 365 App Store.

Important

Informační bariéry Microsoft Purview (IB) se v současné době nepodporují pro správu a sdílení modulů plug-in nebo dovedností. V tenantech, ve kterých je IB povolená, se nahrávání vložených souborů znalostní báze blokuje na úrovni tenanta. Tím se zabrání nahrání nebo publikování dotčených pluginů a dovedností.

Společnost Microsoft nevytváří ani neudržuje žádný trvalý index, znalostní graf (včetně Microsoft Graphu) ani databázi, která by obsahovala obsah ISV, ať už procházením, scrapingem, harvestingem, hromadným exportem, ingestováním nebo jakoukoli jinou metodou (prostřednictvím rozhraní API, serveru MCP nebo jinak). Microsoft může obsah ISV dočasně zpracovat, aby reagoval na dotaz uživatele v reálném čase, ale nezachovává obsah ISV nad rámec doby trvání této relace. Na základě písemné žádosti ISV Microsoft do 10 pracovních dnů vymaže veškerý obsah ISV, který má k dispozici nebo pod kontrolou, a jeho vymazání písemně potvrdí. Další informace o ochraně podnikových dat v Microsoft Copilot a Microsoft Copilot Chat.

Co budete vytvářet

Zásuvný modul Cowork je balíček, který .zip obsahuje:

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

Dovednosti používají open-standard Agent Skills – stejný formát, který podporuje Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie a více než 30 dalších nástrojů AI.

Výběr výchozího bodu

Vytvořte si plugin pomocí wiqd CLI. Rozhraní příkazového řádku vygeneruje balíček a udržuje manifest.json a složky vašich skillů v synchronizovaném stavu. Před nahráním také spustí vlastní ověřovací pravidla platformy a pak nasadí a sdílí výsledek. CLI je v předběžné verzi, takže jeho příkazy a generovaný výstup se mohou před obecnou dostupností změnit. Všechno, co vygeneruje, je běžný balíček aplikace Microsoft 365, takže soubory můžete rovnou otevírat, upravovat a verzovat.

Balíček sestavte ručně pouze tehdy, když nemůžete nainstalovat nástroje nebo když vytváříte vlastní pipeline pro vytváření balíčků. V takovém případě je právě reference k formátu balíčku v tomto článku to, co potřebujete — přesně popisuje, co wiqd vytváří.

Výchozí bod	Udělej to	Čas do prvního balíčku
Začínám od nuly	Vytvořit plugin ve wiqd	asi 10 minut
Už mám plugin Claude Code	Převeďte ho	asi 5 minut
Nemůžu nainstalovat tooling nebo píšu si vlastní skripty pro balení	Sestavit balíček ručně	asi 30 minut

Vytvořte modul plug-in pomocí wiqd

Rozhraní příkazového řádku wiqd má stejný životní cyklus, jaký jinak provádíte ručně – vytvářet, přidávat schopnosti, ověřovat, zřizovat, balit a sdílet. Balíček, který vytvoří, už splňuje ověřovací pravidla v tomto článku.

Krok 1: Nainstalujte wiqd a přihlaste se

Nainstalujte wiqd CLI podle instalační příručky wiqd, která pokrývá Windows, macOS a Linux. Pak se přihlaste k tenantovi Microsoftu 365, pro nějž vyvíjíte, protože zřizování i sdílení obojí pracuje s vaším tenantem:

wiqd auth login --interactive

Instalační program také zaregistruje modul plug-in rozhraní příkazového řádku GitHub Copilot, abyste mohli stejný životní cyklus řídit pomocí konverzačního rozhraní. Můžete například říct Vytvořte samostatný plugin s názvem Triage Helper nebo Ověřte můj plugin. Konverzační cesta spustí stejné příkazy jako tento oddíl. Příkazy můžete použít přímo při skriptování kanálu nebo pokud chcete reprodukovatelnou neinteraktivní automatizaci.

Krok 2: Vytvořit základní strukturu pluginu a přidat možnosti

Vytvořte kontejner pluginu a pak přidejte jakékoli funkce, které potřebujete, v libovolné kombinaci:

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 lešení appPackage/skills/contract-analysis/SKILL.md a zaregistruje jej v agentSkills[]. add connector zapíše položku agentConnectors[]. Oba příkazy před zápisem uplatňují omezení platformy pro názvy a velikost, takže se neshoda názvu složky ani příliš dlouhý název id nikdy nezapíší do manifestu.

Do vygenerované SKILL.mdtabulky napište logiku svých dovedností. Pole v hlavičce metadat, model postupného načítání a limity doprovodných souborů jsou stejné jako ty, které jsou popsány v Krok 1: Vytvoření první dovednosti a Krok 2: Přidání referenčních materiálů (volitelné).

Important

wiqd plugin create připne balíček na manifestVersion: "1.29", zatímco ručně vytvořené příklady v tomto článku používají 1.28. Rozdíl je u konektorů důležitý. Při hodnotě 1.28 je mcpToolDescription povinné a soubor, který označuje, musí být v archivu ZIP. Ve verzi 1.29 jsou položky agentConnectors[] pouze adresy URL a mcpToolDescription je volitelné, takže balíček vygenerovaný wiqd nikdy nenarazí na toto selhání nahrávání. WIQD zatím nepodporuje ověřování konektorů – nakonfigurujte ho přímo, jak je popsáno v tématu Podporované typy ověřování.

Krok 3: Ověřujte během sestavování

Průběžně ověřujte místo sestavování balíčku a doufání, že nahrání proběhne úspěšně:

wiqd plugin validate
wiqd plugin validate --mode deep

validate je offline statická kontrola rozhraní deklarativního agenta. Plugin obsahující pouze dovednosti nebo pouze konektory touto kontrolou projde, protože v něm není co kontrolovat, což je očekávané — jde o kontrolu vaší smyčky sestavení, nikoli o úplné pokrytí. validate --mode deep nejprve zabalí modul plug-in a pak ověří vytvořený .zip ve stejné knihovně pro ověřování aplikací, kterou používá nahrávání. To je místo, kde se objevují kódy ASKILL a pravidla konektorů.

Krok 4: Zřízení, balení a sdílení

Spusťte tyto tři příkazy v uvedeném pořadí:

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

Spusťte provision jako první, protože zapisuje soubor prostředí, na kterém jsou závislé package i share. Pomocí --scope users můžete sdílet obsah s lidmi, které uvedete, nebo pomocí --scope tenant se všemi ve vaší organizaci. V každém případě se plugin zobrazí v Sdílené se mnou v části Cowork>Zdroje a dovednosti>Pluginy. Pokud ho má správce místo toho uvést v sekci Discover, nahraje balíček. Další informace najdete v kroku 8: Publikujte do svého tenanta. Pokud chcete odebrat to, co vytvořil provision, spusťte wiqd plugin delete --env local --yes.

Odeslání do veřejného obchodu je v Partner Center stále ruční proces. Další informace najdete v kroku 9: Publikování pro veřejnost.

Přenést plugin na jiného hostitele

Chcete-li použít své Skills v Claude Code, Cursor nebo jakémkoli jiném hostiteli Agent Skills, exportujte projekt místo ručního kopírování složek:

wiqd plugin export --format claude-plugin

export má jako výchozí hodnotu --format open-plugin a přijímá také cursor-plugin. Zapíše nekomprimovaný adresář pod <path>/export/<format>.

Importovat existující plugin

Pokud již máte plugin Claude Code s dovednostmi a servery MCP, máte dva způsoby převodu. Cesta, kterou zvolíte, závisí na tom, zda plánujete pokračovat ve vývoji pluginu, nebo jen vydat to, co máte.

Cíl	Použít
Pokračujte ve vývoji, ověřování a publikování modulu plug-in pro Microsoft 365	wiqd plugin import
Vytvořte publikovatelný výstup .zip z existujícího pluginu Claude hned	Převodní skript

Import pomocí wiqd

wiqd plugin import rozpozná zdroj pluginu Open Plugin, pluginu Claude nebo pluginu Cursor a vytvoří z něj projekt pluginu wiqd. Importovaný modul plug-in prochází stejným životním cyklem jako modul plug-in, který jste vytvořili 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 a --terms-url jsou vyžadovány pouze při prvním importu plug-inu. Pokud zdroj pocházel z dřívějšího wiqd plugin export, metadata zpáteční cesty je již obsahují.

Important

Importovaný projekt podporuje jen tu část životního cyklu, která je určena pouze ke čtení – wiqd plugin validate, show a list. Zatím se nedá zabalit, zprovoznit ani sdílet, protože import nevytvoří strukturu souborů pro místní nasazení, které tyto kroky vyžadují. Jedná se o sledovanou mezeru v pokrytí. Aktuální stav najdete v referenčních informacích k rozhraní příkazového řádku wiqd. Pokud dnes potřebujete publikovatelný balíček, použijte převodní skript.

Převeďte pomocí převodního skriptu

Převodní skript převádí plugin Claude přímo na balíček M365 připravený k publikování:

1. Nainstalujte rozhraní příkazového řádku (vyžaduje verzi 1.1.12 nebo novější):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Ověřte verzi:

   atk --version
   

3. Importujte svůj plugin:

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

Příkaz přečte adresář .claude-plugin/plugin.json (nebo .cursor-plugin/plugin.json) vašeho modulu plug-in, .mcp.json a adresář skills/ a poté vygeneruje projekt sady nástrojů pro agenty obsahující appPackage/manifest.json, vaše dovednosti a vygenerované ikony.

Musíte zahrnout --privacy-url a --terms-url protože manifesty modulu plug-in nemají ekvivalentní pole a manifest Microsoft 365 vyžaduje obojí.

Note

atk import openplugin Vyhledá manifest pluginu v adresáři s názvem začínajícím tečkou—.claude-plugin/plugin.json, .cursor-plugin/plugin.json nebo .plugin/plugin.json—vedle .mcp.json. Specifikace Agent Plugins 1.0.0 umisťuje manifest do umístění plugin.json a konfiguraci MCP na mcp.json. Chcete-li importovat modul plug-in, který dodržuje rozložení 1.0.0, přesuňte jeho manifest do .plugin/plugin.json a přejmenujte mcp.json na .mcp.json.

Zabalte výsledek do souboru pro nahrání .zip:

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

Note

atk import openplugin devPreview generuje manifest. Příklady manifestů v jiných částech tohoto článku jsou určeny pro schéma verze 1.28. Pokud publikujete prostřednictvím kanálu, který vyžaduje verzi 1.28, aktualizujte manifestVersion a $schema v vygenerovaném appPackage/manifest.json.

Co se importuje

Artefakt zásuvného modulu	Ekvivalent M365	Notes
.claude-plugin/plugin.json	manifest.json	Namapovaná pole názvu, popisu a vývojáře; automaticky vygenerovaný identifikátor GUID (deterministický UUID v5)
skills/*/SKILL.md	agentSkills[] položek + skills/ složek	Doslovně zkopírované – identický formát
.mcp.json servery	agentConnectors[] Položky	Automaticky zjištěna adresa URL a typ ověřování.
color.png / outline.png	Ikony v balíčku	Používá se, pokud je k dispozici; Zástupné symboly vygenerované, pokud chybí

Important

Pro každý konektor importovaný z .mcp.json se vygeneruje zástupný symbol authorization.referenceId odvozený od modulu plug-in a názvu serveru. Před publikováním ho nahraďte skutečným ID registrace klienta OAuth. Další informace najdete v tématu Podporované typy ověřování.

Co není převedeno

Následující funkce modulu plug-in Claude zatím nejsou v manifestu Microsoft 365 podporované:

Funkce pluginu Claude	Status
commands/ (příkazy se lomítkem)	Zatím není podporováno.
agents/ (podřízení agenti)	Zatím není podporováno.
hooks/ (obslužné procedury událostí)	Zatím není podporováno.
settings.json	Nelze použít
bin/ (spustitelné soubory)	Nelze použít

Možnosti importu

Option	Description
--path, -p	Required. Adresář modulu plug-in obsahující .claude-plugin/plugin.json, .cursor-plugin/plugin.jsonnebo .plugin/plugin.json
--output, -o	Cílová složka projektu (výchozí: ./<plugin-name>)
--privacy-url	developer.privacyUrl pro vygenerovaný soubor manifestu
--terms-url	developer.termsOfUseUrl pro vygenerovaný manifest
--website-url	developer.websiteUrl. Použije se homepage, pak author.url
--app-id	Přepište deterministický identifikátor UUID v5 vygenerovaný pro manifest id
--default-auth-type	Auto (výchozí), None, OAuthPluginVaultnebo ApiKeyPluginVault

Automatické zjištění typu ověřování:

Source	Výchozí typ ověřování	Reason
Externí adresy URL protokolu HTTPS	OAuthPluginVault	Většina vzdálených rozhraní API potřebuje autentizaci
localhost a adresy URL jiné než HTTPS	None	Lokální vývojové servery

Pokud automatické rozpoznání neodpovídá vašemu nastavení, použijte --default-auth-type k jeho přepsání.

Export zpět do adresáře pluginů

Chcete-li přesunout projektu sady Agents Toolkit zpět do adresáře modulu plug-in – například za účelem synchronizace modulu plug-in Claude Code a balíčku Cowork – použijte atk export openplugin:

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

Option	Description
--path, -p	Required. Složka projektu Agents Toolkit obsahující appPackage/manifest.json
--output, -o	Cílový adresář pluginu (výchozí: ./<plugin-name>-openplugin)
--manifest-kind	open-plugin (výchozí, zapíše .plugin/plugin.json), claude-pluginnebo cursor-plugin

Export zapíše x-microsoft-365-agents-toolkit blok do vygenerovaného plugin.json. Tento blok nese manifest id, adresy URL pro vývojáře a nastavení konektoru, takže lze později provést obousměrný převod pomocí atk import openplugin bez nutnosti --privacy-url nebo --terms-url znovu.

Note

Blok x-microsoft-365-agents-toolkit je specifický pro Agents Toolkit a výchozí open-plugin druh zapisuje manifest do .plugin/plugin.json. Agent Plugins 1.0.0 používá kořenový element plugin.json a nese data specifická pro klienta pod klíčem extensions s oborem názvů reverzní domény, takže ostatní klienti tento blok spíše ignorují, než aby na něj reagovali. Pokud je vaším cílem Claude kód nebo kurzor, použijte --manifest-kind claude-plugin or cursor-plugin.

Legacy: Konverzní skript PowerShellu

Předtím, než atk podporoval import pluginů, se ke konverzi používal skript PowerShellu pouze pro Windows, který je stále k dispozici jako skript pro konverzi:

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

Místo toho použijte atk import openplugin. Je multiplatformní, podporuje zdroje Cursor i Claude Code a může exportovat zpět do adresáře pluginů.

Sestavte balíček ručně

Tato část je referencí k formátu balíčku: přesně popisuje, co Build a plugin with wiqd generuje, pole po poli. Projděte si tento postup od začátku do konce, pokud nemůžete nainstalovat potřebné nástroje nebo si vytváříte vlastní pipeline pro vytváření balíčků. Použijte jej jako referenční materiál, když potřebujete pochopit vygenerovaný balíček nebo jej ladit.

Krok 1: Vytvořte si svou první dovednost

Dovednost je složka, která obsahuje soubor SKILL.md. Vytvořte následující strukturu složek:

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

Napište SKILL.md pomocí YAML frontmatteru a textu Markdownu:

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

Pole frontmatter v SKILL.md

Povinná pole:

Pole	Constraints	Description
name	1–64 znaků, kebab-case	Identifikátor dovednosti - musí se přesně shodovat s názvem složky
description	1–1024 znaků	Kdy použít tuto dovednost – uveďte spouštěcí fráze

Important

• Název složky se musí shodovat s polem name v frontmatteru. Tento nesoulad je nejčastější příčinou selhání dovedností.
• Pole výpisu description pluginů by neměla obsahovat výzvy k akci, které uživatele nasměrují na externí tržiště, aby si mohli koupit předplatné.

Cesta ke složce	name Pole	Je to platné?	Proč
skills/contract-analysis/SKILL.md	contract-analysis	Yes	Složka a název se shodují
skills/contract-analysis/SKILL.md	ContractAnalysis	No	Název používá PascalCase místo toho, aby odpovídal složce.
skills/my-skill/SKILL.md	contract-analysis	No	Složka je my-skill , ale název je contract-analysis

Pravidla pojmenovávání (kebab-case): Používejte pouze malá alfanumerická písmena a spojovníky. Nepoužívejte po sobě jdoucí pomlčky ani pomlčky na začátku ani na konci.

Example	Je to platné?	Issue
bond-relative-value	Yes	Malá písmena s pomlčkami
fx-carry-trade	Yes	Malá písmena se spojovníky
email	Yes	Jedno slovo, pomlčky nejsou potřeba
Bond_Relative_Value	No	Podtržítka a velká písmena
--my-skill--	No	Počáteční a koncové spojovníky
my--skill	No	Po sobě jdoucí pomlčky

Krok 2: Přidejte referenční materiály (volitelné)

Pro komplexní dovednosti ponechte hlavní SKILL.md co nejjednodušší a přesuňte podrobný obsah do podadresářů. Tyto soubory navíc jsou doprovodné soubory. Dovednost načte, když je to potřeba.

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 doprovodných souborů

Každá dovednost může obsahovat až 20 doprovodných souborů (jakýkoli soubor jiný než SKILL.md). Pro každou dovednost platí následující limity:

Limit	Value
Maximální doprovodné soubory	20
Maximální velikost jednoho doprovodného souboru	5 megabajtů
Maximální celková velikost společníka	10 MB
Vypršení časového limitu stahování (všichni společníci)	15 sekund

Pravidla pro doprovodné soubory

Cesty k doprovodným souborům musí splňovat tato pravidla:

• Používejte pouze relativní cesty (ne absolutní).
• Žádný průchod adresářovou strukturou (.. segmenty).
• V názvech souborů se nevyskytují zpětná lomítka ani bajty null.
• Žádné skryté soubory (názvy začínající na .).
• Žádné vyhrazené názvy systému Windows (CON, PRN, AUX, COM1, NUL–COM9, LPT1–LPT9).
• Samotný soubor SKILL.md se nepočítá jako doprovodný soubor.
• Názvy souborů musí obsahovat bezpečné znaky: alfanumerické znaky, pomlčky, podtržítka, tečky, mezery a !.

Aby bylo kontextové okno efektivní, systém načte dovednosti ve třech vrstvách:

Vrstva	Po načtení	Cílová velikost
Frontmatter (name + description)	Vždy - při spuštění	~100 žetonů
SKILL.md text zprávy	Při aktivaci schopnosti	Méně než 5 000 tokenů (1 500–2 000 slov)
Odkazy (references/)	Na vyžádání agentem	Unlimited
Skripty (scripts/)	Spuštěno, nenačteno do kontextu	N/A

Explicitně SKILL.md odkazujte na podadresáře, aby agent věděl, že existují:

## 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: Přidejte konektor (volitelné)

Pokud vaše rozšíření potřebuje přístup k externím datům, přidejte vzdálený server MCP. Tento krok je volitelný. Balíčky obsahující jen dovednosti jsou vhodné pro pracovní postupy založené na výzvách.

Tip

Pokud váš server řídí viditelnost nástroje podle klienta nebo přiřazuje příchozí provoz, přejděte na Identifikace provozu Coworku na vašem serveru k identitě klienta, kterou Cowork předává.

Note

Vlastní moduly plug-in nejsou v aplikaci Cowork na mobilním zařízení podporovány.

Požadavky konektoru

Requirement	Detaily
Transport	Streamovatelný HTTP (vyžaduje se HTTPS, TLS 1.2+)
Protocol	Formát zprávy JSON-RPC 2.0
Objevování nástrojů	Podpora pro tools/list dynamické zjišťování (doporučeno)
Spouštění nástroje	Podpora tools/call pro volání
Availability	Pro aplikace publikované ve Store se doporučuje SLA s dostupností 99,9 %.
Doba odezvy	Méně než 30 sekund na jedno volání nástroje

Pokyny pro návrh nástrojů

• Jeden nástroj na akci pro malá rozhraní API (méně než 15 operací): search_case_law, get_ruling, cite_precedent
• Hledání + spouštění velkých rozhraní API (50+ operací): search_actions + execute_action
• Popisné názvy: get_bond_price ne getData
• Schémata s bohatými vstupy: Zahrňte popis každého parametru – to je to, co agent čte
• Strukturovaný výstup: Vrátí JSON, který může agent naformátovat pro uživatele
• Vstupy souborů: Pokud chcete přijmout soubor z pracovního prostoru uživatele, deklarujte parametr pomocí contentEncoding: base64. Další informace najdete v článku Přijímat soubory z pracovního prostoru Cowork.

Popište nástroje konektoru (mcpToolDescription)

Spojnice remoteMcpServer může volitelně obsahovat mcpToolDescription objekt. Pokud je k dispozici, její vnořená file vlastnost odkazuje na soubor JSON s popisem nástroje, který zabalíte uvnitř .zip a odkazujete na něj relativní cestou z kořene balíčku. Cowork dynamicky zjišťuje nástroje z vašeho MCP serveru a nepoužívá tento soubor, i když je přítomen.

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

Pokud zahrnete mcpToolDescription, odkazovaný soubor (například tools/contoso-legal-tools.json) popisuje nástroje, které konektor zpřístupňuje, a musí být přítomen v balíčku ZIP. Při zabalení modulu plug-in jej zahrňte vedle své manifest.json složky a skills/ složka.

Tip

Tento požadavek platí pro manifest verze 1.28. Balíčky, které generuje wiqd plugin create, cílí na verzi 1.29, v níž položky agentConnectors[] obsahují pouze adresu URL, mcpToolDescription je volitelné a není tu žádný soubor s popisem nástroje, na který by se dalo zapomenout.

Podporované typy ověřování

Typ ověřování	Kdy ho použít	Uživatelské prostředí
None	Veřejná nebo anonymní rozhraní API, interní služby	Transparentní – žádná výzva k ověření
OAuthPluginVault	Rozhraní API OAuth 2.0 (doporučená pro produkční nasazení)	Uživatel dokončí souhlas s OAuth pouze jednou
ApiKeyPluginVault	Služby založené na klíčích API	Uživatel zadá klíč pouze jednou

Note

• Podpora ověřování pomocí klíče API zatím není v aplikaci Cowork dostupná.
• Pokud váš server MCP vyžaduje klíč API, použijte OAuthPluginVault místo toho nebo Dynamická registrace klienta nebo zpřístupněte koncový bod, který akceptuje None.

Pro OAuthPluginVault a ApiKeyPluginVaultreferenceId odkazuje na přihlašovací údaje uložené v úložišti tokenů Microsoft Enterprise – tajné údaje se nikdy nezobrazují v souborech manifestu nebo skillů. Hodnota referenceId je ID registrace klienta OAuth, které vytvoříte při registraci klienta OAuth pomocí Agents Toolkit.

Important

Při registraci klienta OAuth nastavte možnost použití podle organizace na Jakákoli organizace Microsoft 365, aby váš modul plug-in fungoval napříč tenanty.

Ověřování MCP

Pokud chcete pro ověřování použít OAuth nebo ApiKey, podrobnosti o nastavení a konfiguraci najdete v článku Konfigurace ověřování pro moduly plug-in MCP a rozhraní API v agentech v Microsoftu 365 Copilot.

Dynamická registrace klienta

Pokud váš server MCP podporuje dynamickou registraci klienta (DCR), můžete vynechat konfiguraci authentication z definice konektoru a Cowork automaticky vytvoří klienta OAuth jménem vašeho modulu plug-in.

Note

Vynechání authentication konfigurace je podporované jenom v aplikaci Cowork. To není v Copilot Chat podporováno. Pokud váš modul plug-in musí fungovat také ve službě Copilot Chat, nakonfigurujte OAuthPluginVault ověřování, jak je popsáno v tématu Podporované typy ověřování.

Objekt můžete úplně vynechat authorization . Nakonfigurujte adresu URL serveru MCP a Cowork se postará o klienta OAuth:

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

Krok 4: Vytvoření manifestu

V kořenovém adresáři balíčku vytvořte manifest.json. Příklad používá manifest verze 1.28; wiqd plugin create místo toho připne hodnotu 1.29, kde položky konektoru obsahují pouze adresy 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" }
  ]
}

Pokud chcete přidat konektor, musíte zahrnout 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"
          }
        }
      }
    }
  ]
}

V konfiguraci konektoru by referenceId mělo být ID registrace OAuth. Pokud zahrnete mcpToolDescription, jeho file musí odkazovat na soubor JSON s popisem nástroje, který je součástí balíčku ZIP.

Important

Schéma manifestu v1.28 je striktní: nastavuje v kořeni additionalProperties: false, takže všechna pole, která nejsou definovaná ve schématu, se odmítnou. Pole, která jsou platná ve standardních manifestech aplikace Teams – například packageName – způsobí, že nahrávání selže s chybou, jako je Property 'packageName' has not been defined and the schema does not allow additional properties.. Zahrňte pouze zde uvedená pole.

Krok 5: Přidání ikon

Vytvořte dvě ikony PNG:

Icon	Velikost	Purpose
color.png	192×192 px	Plnobarevná ikona aplikace zobrazená ve Store a seznamu aplikací
outline.png	32×32 px	Jednobarevná obrysová ikona pro kompaktní zobrazení

Pokud ještě ikony nemáte, atk import openplugin vygeneruje jednobarevné zástupné prvky. Před odesláním do Storu je nahraďte.

Krok 6: Balení

Vytvořte soubor ZIP s veškerým obsahem na kořenové úrovni. wiqd plugin package( Vytvoří stejnou strukturu 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

Pokud konektor obsahuje mcpToolDescription, zahrňte soubor JSON s popisem nástroje, na který konektor odkazuje. Balíčky, které nepoužívají mcpToolDescription, včetně balíčků pouze dovedností, nepotřebují tools/ složku.

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/

Použití sady nástrojů Microsoft 365 Agents Toolkit

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

Krok 7: Otestujte

Pokud chcete aplikaci otestovat, nahrajte balíček aplikace do Teams, jak je popsáno v části Nahrání aplikace do Teams.

Pokud jste modul plug-in vytvořili pomocí wiqd, spusťte wiqd plugin provision ho – modul plug-in zaregistruje ve vašem tenantovi za vás. Pro osobní testování ručně sestaveného balíčku nahrajte aplikaci bokem pomocí rozhraní příkazového řádku sady Microsoft 365 Agents Toolkit:

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

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Instalaci ověřte spuštěním následujícího příkazu:

   atk --version
   

3. Ověřte se pomocí svého pracovního účtu Microsoft 365:

   atk auth login
   

4. Přihlaste se ke svému pracovnímu účtu a nainstalujte si balíček agenta. Nahraďte cestu k souboru cestou k umístění balíčku ZIP:

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

   Úspěšná instalace vrátí výstup, který obsahuje TitleId a AppId pro váš účet.

5. Tato ID si uložte pro pozdější použití při aktualizaci nebo odinstalaci.

Další informace najdete v rozhraní příkazového řádku sady nástrojů Microsoft 365 Agents.

Krok 8: Publikování do tenanta

Nahrajte balíček do Centra pro správu a zařadíte modul plug-in do sekce Zjistit , kde ho může najít kdokoli z vaší organizace:

1. Otevřete >Správa aplikací>Nahrajte vlastní aplikaci.
2. Vyberte tlačítko se třemi tečkami (...) >Přidat agenta.
3. Nahrajte svůj .zip balíček.
4. Otevřete Cowork>>. Váš plugin se zobrazí v sekci Discover.

wiqd plugin share modul plug-in umístí do složky Sdílené se mnou, nikoli do složky Discover. Použijte ho pro testování a cílené nasazení u konkrétních lidí. Nahrání do Centra pro správu způsobí, že se modul plug-in zobrazí pro zjišťování.

Krok 9: Publikovat pro veřejnost

V případě modulů plug-in určených k veřejné distribuci odešlete modul plug-in do Microsoft 365 App Store prostřednictvím Partner Center. Další informace najdete v tématu Publikování agentů pro Microsoft 365 Copilot.

Otestujte konektor proti místnímu serveru MCP

Konektory vyžadují HTTPS mcpServerUrl. Pokud chcete otestovat server běžící na vašem počítači, musíte ho zpřístupnit prostřednictvím veřejné adresy URL HTTPS. Vývojové tunely poskytují přenosovou službu, která za vás ukončuje TLS.

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

Important

Použít --protocol http, ne https. Tento --protocol příznak popisuje místní službu, na kterou tunel přeposílá, nikoli adresu URL veřejného tunelu. Většina lokálních MCP serverů hovoří prostým HTTP, takže pokud nastavíte --protocol https , zatímco váš server obsluhuje HTTP, každý požadavek tunelem vrátí chybu 502 . Relé zajišťuje ukončení TLS a poskytuje veřejnou adresu URL přes protokol HTTPS bez ohledu na tento příznak.

Troubleshooting

Symptom	Cause	Opravit
Každý tunelový požadavek se vrátí 502 a místní server komunikuje přes HTTP	devtunnel port create byl spuštěn pomocí --protocol https	Opětovné vytvoření portu pomocí --protocol http
Požadavky tunelového propojení se v macOS vracejí 502 , i když je místní server spuštěný	Server je navázán na 0.0.0.0 (pouze IPv4), ale tunel vytočí localhost, což se nejprve přeloží na adresu ::1 (IPv6)	Navažte server na ::, aby přijímal připojení IPv4 i IPv6
Nahrání se nezdaří kvůli Property '<field>' has not been defined and the schema does not allow additional properties	Manifest obsahuje pole, které schéma v1.28 nepovoluje (například packageName)	Odeberte pole; schéma v1.28 používá additionalProperties: false

Vzory balení

Zvolte vzor, který se hodí k vašemu rozšíření:

Jen dovednosti (bez konektoru)

Nejvhodnější řešení pro pracovní postupy založené na promptech, analýzu dokumentů a pomoc při psaní.

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

Dovednosti + vzdálené připojení

Nejvhodnější řešení pro analýzu dat, integraci rozhraní API a podnikové systémy.

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

Pouze konektor (žádné vlastní dovednosti)

Tuto možnost použijte pro zdroje dat, které už integrované dovednosti aplikace Cowork můžou používat.

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

Importovaný plugin Claude Code nebo Cursor

Tuto možnost použijte pro existující moduly plug-in ekosystému Claude, které cílí na Cowork. Pokud chcete pokračovat ve vývoji modulu plug-in v Microsoft 365, importujte ho:

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

Chcete-li ze zásuvného modulu v jeho současné podobě vytvořit publikovatelný .zip, použijte převodní skript:

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

Osvědčené postupy pro tvorbu dovedností

Postupujte podle těchto pokynů k vytváření dovedností, které se spolehlivě aktivují a přinášejí konzistentní výsledky.

Psaní efektivních popisů

Pole description určuje, kdy agent aktivuje váš skill. Buďte konkrétní:

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

Napište efektivní pracovní postupy

• V popisu buďte konkrétní. Zahrňte spouštěcí fráze: "Použijte, když uživatel požádá o..." Tímto popisem se agent rozhoduje, kterou dovednost aktivovat.
• Uspořádat jako pracovní postup. Očíslujte kroky. Každý krok by měl být mapován na konkrétní akci (čtení souboru, volání nástroje, generování výstupu).
• Definujte výstupní formát. Zobrazit přesnou strukturu tabulky, seznamu nebo dokumentu, kterou uživatelé očekávají Tato definice výrazně zlepšuje konzistenci.
• Odkázat na nástroje podle názvu Pokud vaše dovednost závisí na nástrojích konektoru, uveďte je výslovně: „Použijte nástroj search_case_law k...“
• Udržujte hlavní soubor SKILL.md stručný. Podrobnou referenční dokumentaci přesuňte do podadresáře references/. Tělo dovednosti by mělo být pracovním postupem, ne encyklopedií.

Vyhněte se běžným chybám

• Nevkládejte tajné údaje do souborů SKILL.md. Použijte agentConnectors pro ověřování přihlašovacích údajů rozhraní API.
• Neduplikujte integrované dovednosti. Před sestavením zkontrolujte seznam integrovaných dovedností.
• Nedělejte dovednosti příliš obecné. „Dělat cokoli s právními dokumenty“ je horší než konkrétní dovednosti pro „analýzu smluv“, „extrakci doložek“ a „právní rešerši“.
• Nevkládejte napevno cesty k souborům ani systémové příkazy. Dovednosti by měly být přenositelné mezi prostředími.
• Nedávejte všechno do SKILL.md. Pokud váš text přesahuje ~3 000 slov, přesuňte podrobný obsah do references/.

Pravidla ověřování

Když odešlete balíček, platforma jej ověří na několika úrovních. Opravte tyto chyby před odesláním, abyste se vyhnuli zamítnutí.

Chcete-li je zachytit během sestavování místo při nahrávání, spusťte wiqd plugin validate --mode deep. Tento příkaz zabalí modul plug-in a spustí stejná pravidla místně. Další informace najdete v kroku 3: Ověřování při sestavování.

Ověření na úrovni manifestu

Code	Rule	Severity
ASKILL-M001	folder je vyžadován v každé agentSkills položce	Error
ASKILL-M002	agentSkills Pole může obsahovat až 20 položek	Error
ASKILL-M003	folder cesta může mít až 256 znaků	Error

Ověření na úrovni balíčku

Code	Rule	Běžné řešení	Severity
ASKILL-P001	Složka, na kterou se odkazuje v manifestu, existuje v ZIP.	Kontrola struktury souboru ZIP	Error
ASKILL-P002	Složka obsahuje SKILL.md soubor	Přidat chybějící SKILL.md	Error
ASKILL-P003	SKILL.md má platná metadata YAML mezi oddělovači ---	Opravte syntaxi YAML	Error
ASKILL-P004	Hlavička obsahuje pole name	Přidat name: do frontmatter	Error
ASKILL-P005	Frontmatter obsahuje pole description	Přidat description: do úvodních metadat	Error
ASKILL-P006	name Odpovídá názvu složky (poslední segment cesty).	Přejmenujte složku nebo opravte name:	Error
ASKILL-P007	name je kebab-case	Použijte my-skill, ne MySkill ani my_skill	Error
ASKILL-P008	V poli nejsou žádné duplicitní hodnoty folder	Odebrání duplicit	Error

Ověření konektoru

Rule	Severity
Každý konektor vyžaduje id a displayName	Error
Všechny hodnoty konektoru id musí být v manifestu jedinečné	Error
Přesně jeden z plugin nebo remoteMcpServer	Error
mcpServerUrl Musí se jednat o platnou adresu URL protokolu HTTPS	Error
Pokud mcpToolDescription je přítomen, musí jeho file existovat v souboru ZIP	Error
authorization.referenceId je povinný, pokud typ není None	Error
authorization.referenceId nesmí být přítomen, pokud je typ None	Error

Ověření doprovodného souboru

Portál ověřuje doprovodné soubory (referenční materiály, skripty a další soubory spolu s nimi SKILL.md) v době nahrávání a synchronizace:

Rule	Severity
Maximálně 20 doprovodných souborů pro každou dovednost (kromě SKILL.md)	Error
Každý doprovodný soubor musí mít 5 MB nebo méně	Error
Celková velikost doprovodných souborů musí být 10 MB nebo méně na jednu dovednost	Error
Cesty k souborům musí být relativní (žádné absolutní cesty).	Error
Žádné segmenty průchodu cestou (..)	Error
V názvech souborů nesmí být zpětná lomítka ani bajty null.	Error
Žádné skryté soubory (názvy začínající na .)	Error
Žádné vyhrazené názvy Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9)	Error
V názvech souborů se musí používat jenom bezpečné znaky (alfanumerické znaky, pomlčky, podtržítka, tečky, mezery, !)	Error

Kompatibilita mezi platformami

Dovednosti používají otevřený standard Agent Skills. Stejné SKILL.md soubory fungují v několika nástrojích AI:

Platform	Compatibility
Kód Claude	zcela stejný SKILL.md formát
Projekty Claude.ai	Full-skills lze nahrát jako projektové soubory
VS Code / GitHub Copilot	Dovednosti Full-Agent podporované v režimu agenta
Rozhraní příkazového řádku Gemini	Podporované dovednosti Full-Agent
JetBrains Junie	Podporované dovednosti Full-Agent
OpenAI kodex	Podporované dovednosti Full-Agent
Cursor	Podporované dovednosti Full-Agent

Pokud rozvíjíte dovednosti pro Claude Code i Copilot Cowork, vytvořte plugin pomocí wiqd. Pak spusťte wiqd plugin export --format claude-plugin, čímž vytvoříte rozložení Claude Code. Pokud byste raději začali od struktury pluginu Claude Code – je to nadmnožina – rozložení je:

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)

Až budete připravení publikovat do Microsoft 365 App Store, přeneste ho do Microsoft 365, a to buď s wiqd plugin import, nebo pomocí převodního skriptu:

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

Správa anotací MCP a potvrzení

Copilot Cowork přečte standardní objekt MCP annotations v nástrojích, které váš server vrací z tools/list, a použije jej k rozhodnutí, zda volání nástroje vyžaduje potvrzení uživatele a jaký popisek se má zobrazit na výzvě.

Dostupná pole

Pole	Typ	Účinek
readOnlyHint	bool	false: Před spuštěním nástroje je vyžadováno potvrzení.
destructiveHint	bool	true: Před spuštěním nástroje je vyžadováno potvrzení.
title	řetězec	Popisek čitelný člověkem zobrazený v potvrzovacím dialogu. Pokud chybí, použije se název nástroje jako záložní hodnota.

Potvrzovací pravidla

Potvrzení je vyžadováno, pokud readOnlyHint == false nebo destructiveHint == true.

Všechny nástroje musí mít uvedené bezpečnostní poznámky. Nástroje bez poznámek jsou považovány za destruktivní a vyžadují potvrzení. Další informace najdete v referenčních informacích ke schématu MCP.

Příklady MCP

Destruktivní akce s přátelským štítkem:

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

Bezpečná operace čtení, která se spustí automaticky:

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

Co je teď k dispozici

• Nástroje Microsoftu (Graph, Dataverse a další) podléhají vestavěné zásadě Coworku bez ohledu na poznámky.
• U serverů MCP jiných společností než Microsoft se potvrzení řízené anotacemi zavádí postupně. Nastavení nápověd nyní zajišťuje budoucí kompatibilitu a s postupným rozšiřováním nasazení se budou zobrazovat výzvy k potvrzení, aniž by byly nutné jakékoli změny na straně vývojáře.

Přijímat soubory z pracovního prostoru Cowork

Nástroj konektoru může jako vstup použít soubor z uživatelovy relace v Coworku — dokument, který uživatel přiložil, e-mailovou přílohu, kterou Cowork uložil, nebo soubor vytvořený v předchozím kroku. Deklarujte parametr pomocí standardního klíčového slova contentEncoding: base64 JSON Schema a Cowork se postará o zbytek. Není vyžadováno žádné rozšíření schématu specifické pro Microsoft a rozhraní API vašeho serveru se nemění.

Cowork soubor workspace zpracuje a zakóduje do base64 předtím, než zavolá váš server, takže se bajty souboru nikdy nedostanou do kontextu agenta. Agent vždy vidí a generuje pouze cesty k souborům pracovních prostorů.

Note

Nedávejte agentovi pokyn, aby soubor sám zakódoval do Base64 a vložil tento blob do volání nástroje. Tento přístup načte celý soubor do kontextu modelu a závisí na modelu, který blob přesně reprodukuje. Zdá se, že funguje na malých testovacích souborech a selhává na skutečných souborech.

Deklarujte parametr souboru

Vlastnost řetězce s contentEncoding: base64 je rozpoznána jako pole pro nahrání souboru:

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

Pole takových řetězců je rovněž podporováno pro nástroje, které přijímají několik souborů:

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

Co vidí makléř

U parametrů souboru deklarovaných na nejvyšší úrovni inputSchema.properties je Cowork ve schématu určeném pro model nahradí jediným polem direct_attachment_file_paths – stejným parametrem, který používají integrované nástroje Cowork, takže agent už ví, jak ho naplnit. Výše uvedené schéma se agentovi zobrazí jako:

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

Pokud váš nástroj deklaruje více než jeden parametr typu soubor na nejvyšší úrovni, všechny se sloučí do jediného pole direct_attachment_file_paths. Při volání Cowork rozepíše vyřešené soubory zpět do původních názvů parametrů v pořadí deklarací.

Parametry vnořeného souboru

Agent podporuje parametr typu soubor vnořený v objektu nebo v poli objektů. Agent tento parametr zpracovává odlišně: místo aby jej sbalil, agent jej přepíše na místě do řetězce cesty ve svém vlastním umístění. Tento přístup zachová přidružení mezi souborem a souvisejícími poli. Například získáte jednu stvrzenku na každý řádek výdajů:

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

Agent vyplní line_items[].receipt cestou k pracovnímu prostoru a Cowork před přesměrováním volání vymění jednotlivé cesty přímo na místě za obsah base64.

Vnoření je procházeno do hloubky čtyř úrovní pod vrcholem inputSchema. $ref Na odkazy se nepřechází – parametry souboru definujte v řádku, nikoli za $ref.

Co váš server obdrží

Váš server obdrží běžnou hodnotu tools/call s původními názvy parametrů naplněnými obsahem kódovaným v base64:

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

Váš server nemusí vědět, že agent použil rozhraní založené na cestě, a nástroje, které nedeklarují contentEncoding: base64 parametry, nejsou ovlivněny.

Limits

Limit	Value
Soubory na jedno volání nástroje	8
Velikost na soubor	150 MiB
Celková velikost na jedno volání nástroje	150 MiB
Parametry souboru pole pro každý nástroj	1 (zkombinujte ho s libovolným počtem skalárních parametrů souboru)
Maximální hloubka vnoření	4 úrovně pod vrcholem inputSchema

Volání, které překročí počet souborů nebo omezení velikosti, selže s chybou nástroje a nikdy nedorazí na váš server. Dimenzujte API a jeho časové limity s ohledem na strop 150 MiB: base64 nafoukne datovou část zhruba o třetinu oproti nezpracované velikosti souboru a kódovaný obsah se odesílá do textu požadavku JSON-RPC.

Recommendations

• Popište parametr pro lidského čtenáře. Agent na základě popisu určí, který soubor patří ke kterému parametru. Například funguje "The signed contract PDF to analyze" lépe než "file".
• V popisu parametru uveďte formáty, které přijímáte. Cowork propustí vše, co uživatel připojí. Ověřte typ obsahu na své straně a vraťte jasnou chybu nástroje, pokud jej nelze použít.
• Nastavení anotací. Nástroj, který přijme soubor a provede nad ním akci, obvykle není jen pro čtení, takže zobrazí výzvu k potvrzení. Další informace najdete v správě anotací a potvrzování MCP.
• Ponechat parametry souboru vložené. Parametr za $ref, nebo vnořený hlouběji než čtyři úrovně, se nepřepíše. Server obdrží řetězec cesty tam, kde očekává obsah.
• Deklarujte maximálně jeden parametr maticového souboru na nástroj. U dvou nebo více souborů nemůže aplikace Cowork určit, který soubor patří do kterého pole, a volání selže s chybou nástroje. Použijte jednu matici nebo několik skalárních parametrů nebo kombinaci skalárů a jednu matici.
• Očekávejte přesný počet nástrojů pouze pro skalární hodnoty. Pokud váš nástroj deklaruje pouze skalární parametry souboru, musí počet souborů, které agent předává, odpovídat deklarovanému počtu. Označte volitelné parametry souboru jasně v jejich popisech, aby agent neposkytl ani příliš málo, ani příliš mnoho.

Note

Tento mechanismus předchází vlastní práci Model Context Protocolu na zadávání souborů, která je standardizována pracovní skupinou MCP File Uploads. Cowork může přidat podporu pro standardizovanou formu deklarativních vstupů souborů, jakmile dorazí. Zde contentEncoding: base64 popsaná smlouva nadále funguje.

Identifikujte provoz Cowork na váš server

Pokud váš server MCP omezuje viditelnost nástrojů podle klienta nebo chcete určit původ přijatého provozu, můžete rozpoznat požadavky, které pocházejí z Cowork. Cowork představuje stabilní softwarovou identitu ve dvou kanálech:

Channel	Kde se zobrazuje	Value
User-Agent hlavička požadavku	Každý odchozí požadavek, který Cowork odešle na váš server	copilot-cowork/1.0
clientInfo v MCP initialize navázání spojení	Pouze požadavek initialize	{ "name": "copilot-cowork", "version": "<version>" }

Porovnat podle předpony copilot-cowork

Musí používat předponucopilot-cowork bez rozlišování velkých a malých písmen na kterémkoli kanálu. Neodpovídají přesnému copilot-cowork/1.0 řetězci nebo konkrétnímu clientInfo.version. Verze se řídí kontraktem identity klienta a očekává se, že se bude měnit; prefixová shoda udrží vaši bránu funkční i přes změny verzí.

# Correct: case-insensitive prefix match
copilot-cowork

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

Vyberte si správný kanál pro vaši bránu

Tyto dva kanály mají různé obory, takže se zaměřte na ten, který odpovídá tomu, jak váš server vynucuje svou bránu:

• Hlavička User-Agent se nachází v každém požadavku, včetně tools/list a tools/call. Pokud budete bránu nebo atribut na požadavek, klíč v této hlavičce.
• clientInfo se odešle initialize při handshake. Pokud to omezíte na jednu relaci v době připojení, můžete si to tam přečíst, ale u dalších požadavků se to neopakuje.

Co identita zahrnuje a nezahrnuje

Identita označuje pouze tento software . Je stejná pro každého uživatele a připojení ke službě Cowork a nikdy nenese identitu uživatele. Identita uživatele zůstane v autorizačním procesu, který definuje konfigurace ověřování vašeho konektoru.

Identita zahrnuje	Identita nezahrnuje
Stabilní název softwaru (copilot-cowork) a smluvní verze	Libovolný identifikátor tenanta, uživatele, relace nebo konverzace
Stejná hodnota u každého požadavku a každého připojení	Kvalifikátor pro každý konektor

Vzhledem k tomu, že neexistuje žádný kvalifikátor pro jednotlivé konektory, nemůžete v současné době použít tuto identitu k určení, který konektor provedl volání, nebo k oddělení publikovaného modulu plug-in Microsoftu od bokem načteného serveru směřujícího na stejnou adresu URL. Pokud toto rozlišení potřebujete, vynuťte ho prostřednictvím konfigurace autorizace vašeho konektoru, nikoli identity klienta.

Časté dotazy

Můžu v kódu Claude použít dovednosti z balíčku M365?

Yes. Složky dovedností obsahují standardní Dovednosti agenta. Spusťte wiqd plugin export --format claude-plugin pro vytvoření rozvržení Claude Code nebo zkopírujte složky skillů do .claude/skills/ v libovolném projektu Claude Code.

Potřebuji Remote Connector?

No. Balíčky pouze s dovednostmi se dobře hodí pro pracovní postupy založené na promptech. Konektory jsou potřeba, jenom když vaše dovednost vyžaduje živá data z externího systému.

Jak se dovednosti pluginů liší od vestavěných dovedností?

Dovednosti modulu plug-in se zobrazují se zdrojovým kódem "package" v rozhraní API. Nemůžou nahradit integrované dovednosti se stejným názvem. Správa nasazené balíčky zobrazují isAdminDeployed: true.

Mohou správci IT spravovat, které pluginy jsou k dispozici?

Yes. Platí standardní ovládací prvky správce M365: seznamy povolených/blokovaných na úrovni tenanta, nasazení spravovaná správcem a zásady dodržování předpisů.

Co se stane, když je plugin zrušen?

V dalším cyklu synchronizace se dovednosti a konektory z daného balíčku odeberou z relace uživatele. Probíhající konverzace se nepřeruší, ale nové relace nebudou mít funkce balíčku.

Jaký je maximální počet dovedností v balíčku?

Dvacet (20) dovedností (dle ASKILL-M002). U konektorů je limit 10 na balení.

Mohou dovednosti odkazovat na nástroje konektorů ze stejného balíčku?

Ano a měli by. Nástroje v pracovním postupu explicitně pojmenujte SKILL.md (například "Použít search_case_law nástroj k..."). Agent je připojí za běhu.

Mohou nástroje mého pluginu přijímat soubory z pracovního prostoru Cowork?

Yes. Deklarujte parametr nástroje pomocí contentEncoding: base64a Cowork před voláním serveru vyřeší soubor pracovního prostoru uživatele na obsah base64. Model předává cesty k souborům, nikoli obsah souborů, takže velké soubory nespotřebovávají kontext modelu. Další podrobnosti o deklaracích a omezeních najdete v tématu Přijímání souborů z pracovního prostoru aplikace Cowork.

Jak vygeneruji deterministický identifikátor GUID pro svůj balíček?

wiqd plugin create za vás vygeneruje a připne ID aplikace. Převodní skript používá UUID v5 (založený na SHA-1) z názvu modulu plug-in, takže spuštění převodu dvakrát vytvoří stejný identifikátor GUID. Pro ruční balení použijte libovolný generátor identifikátorů GUID. Ujistěte se, že je stabilní napříč verzemi.

Na kterou verzi manifestu se mám zaměřit?

Cíl 1.29, pokud stavíte pomocí wiqd, což vám ho připne. Ve verzi 1.29 obsahují položky agentConnectors[] pouze adresy URL a mcpToolDescription je volitelné. V ručně vytvořených příkladech v tomto článku se používá verze 1.28, kde je vyžadováno mcpToolDescription a soubor, který označuje, musí být v archivu ZIP. atk import openplugin používá UUID v5 (založený na SHA-1) z názvu vašeho pluginu. Při dvojím spuštění importu se vytvoří stejné GUID. Pokud chcete nastavit vlastní, zadejte --app-id. Pro ruční balení použijte libovolný generátor identifikátorů GUID. Ujistěte se, že je stabilní napříč verzemi.

Související obsah

• Přehled Cowork
• Použít Cowork
• Spravujte Cowork pro svou organizaci
• Spravovat pluginy pro Cowork
• wiqd plugin CLI referenční příručka