Copilot Coworkin laajennusten muodostaminen

Koskee seuraavia:: Microsoft Copilot

Microsoft Copilot Cowork tukee laajennettavuutta M365-sovelluspakettien kautta; myös Teams-sovellukset, Copilot-agentit ja Office-lisäosat käyttävät samaa jakelumekanismia. Coworkin laajennustavat:

Taidot: kehotepohjaiset työnkulut, jotka opettavat Coworkille asiantuntevasti uutta toimialaa, kuten rahoitusanalyysin, juridisen tutkimuksen tai henkilöstöhallinnon työnkulkuja.
Yhdistimet: etäpalvelimet, joiden avulla Cowork voi käyttää ulkoisia tietolähteitä ja ohjelmointirajapintoja.

Molemmat on pakattu tavalliseen Microsoft 365 -sovelluspakettiin, ja niitä jaetaan Microsoft 365 App Storen kautta.

Tärkeää

Microsoft Purview'n tietoesteitä ei tueta tällä hetkellä tueta laajennuksia tai taitoja hallittaessa ja jaettaessa. Jos tietoraja on otettu vuokraajassa käyttöön, upotetut tietämystiedostojen lataukset estetään vuokraajatasolla. Tämä estää laajennusten ja taitojen lataamisen tai julkaisemisen, joihin ongelma vaikuttaa.

Microsoft ei luo tai ylläpidä pysyvää indeksiä, tietämyskaaviota (mukaan lukien Microsoft Graph) tai tietokantaa, joka sisältää ISV-sisältöä, olipa kyseessä oleva menetelmä indeksointi, haalinta, kerääminen, joukkovienti, käsittely tai jokin muu (ohjelmointirajapinnan tai MCP-palvelimen kautta tai jollain muulla tavoin). Microsoft saattaa käsitellä ISV-sisältöä tilapäisesti tarpeen mukaan käyttäjän reaaliaikaiseen kyselyyn vastaamiseksi, mutta ei säilytä ISV-sisältöä kyseisen istunnon keston jälkeen. Microsoft poistaa hallussaan tai hallinnassaan olevan ISV-sisällön ISV:n kirjallisesta pyynnöstä 10 arkipäivän kuluessa ja vahvistaa poistamisen kirjallisesti. Lisätietoja on kohdassa Yritystietojen suojaus Microsoft Copilotissa ja Microsoft Copilot Chatissa.

Koostettu sisältö

Cowork-laajennus on .zip paketti, joka sisältää:

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

Taidot käyttävät Agent Skills open -standardia – samaa muotoa, jota tukevat Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie ja yli 30 muuta tekoälytyökalua.

Aloituskohdan valinta

Luo laajennus wiqd CLI:n avulla. CLI luo paketin rungon ja pitää manifest.json ja skill-kansiosi synkronoituina. Se myös suorittaa alustan omat validointisäännöt ennen lataamista, minkä jälkeen se ottaa käyttöön ja jakaa tuloksen. Komentorivikäyttöliittymä on esiversiovaiheessa, joten sen komennot ja luotu tulos voivat muuttua ennen yleistä saatavuutta. Sen luoma sisältö on tavallinen Microsoft 365 -sovelluspaketti, joten voit edelleen avata ja muokata tiedostoja sekä hallita niiden versioita suoraan.

Kokoa paketti manuaalisesti vain silloin, kun työkaluja ei voi asentaa tai kun rakennat oman pakkausputken. Tämän vuoksi tämän artikkelin pakkausmuotoviite on välttämätön, sillä siinä kuvaillaan täsmälleen, mitä wiqd tuottaa.

Lähtökohta	Tee tämä	Aika ensimmäiseen pakettiin
Aloitetaan alusta	Luo lisäosa wiqdillä	noin 10 minuuttia
Minulla on olemassa oleva Claude Code -laajennus	Muuntaminen	noin 5 minuuttia
Työkaluja ei voi asentaa tai luodaan oma paketointikomentosarja	Pakkaus kootaan käsin	noin 30 minuuttia

Laajennuksen muodostaminen wiqd:n avulla

wiqd-komentorivikäyttöliittymä suorittaa saman elinkaaren, joka muutoin suoritettaisiin manuaalisesti eli se luodaan ja ominaisuudet lisätään, minkä jälkeen se tarkistetaan, valmistellaan, pakataan ja jaetaan. Sen tuottama paketti täyttää jo tässä artikkelissa esitetyt validointisäännöt.

Asenna wiqd CLI noudattamalla wiqd-asennusopasta, joka kattaa Windowsin, macOS:n ja Linuxin. Kirjaudu sitten siihen Microsoft 365 -tenanttiin, jota vastaan kehität, koska sekä provisiointi että jakaminen kohdistuvat tenanttiisi:

wiqd auth login --interactive

Asennusohjelma rekisteröi myös GitHub Copilot CLI -laajennuksen, jotta voit hallita samaa elinkaarta keskustelumuotoisesti. Voit esimerkiksi sanoa: Luo itsenäinen laajennus nimeltä Triage Helper tai Tarkista laajennukseni. Keskustelun kulku suorittaa samat komennot kuin tässä osiossa. Käytä komentoja suoraan, kun kirjoitat putken komentosarjaa tai haluat toisinnettavan, muun kuin vuorovaikutteisin automaation.

Vaihe 2: Luo laajennuksen runko ja lisää ominaisuudet

Luo laajennussäilö ja lisää sitten tarvittavat ominaisuudet sopivina yhdistelminä:

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 muodostaa rungon komennossa appPackage/skills/contract-analysis/SKILL.md ja rekisteröi sen komennossa agentSkills[]. add connector kirjoittaa agentConnectors[] merkinnän. Molemmat komennot valvovat ympäristön nimi- ja kokorajoituksia ennen kirjoittamista sekä estävät tällä tavoin kansion nimiristiriidan tai liian pitkän id-tunnuksen pääsyn kokoonpanotietoihin.

Kirjoita taitologiikkasi luotuun SKILL.md. Edustakentät, etenevä latausmalli ja kumppanitiedoston rajoitukset ovat samat, joita käsiteltiin kohdissa Vaihe 1: Ensimmäisen taidon luominen ja Vaihe 2: Viitemateriaalin lisääminen (valinnainen).

Tärkeää

wiqd plugin create kiinnittää paketin versioon manifestVersion: "1.29", kun taas tämän artikkelin käsinkirjoitetuissa esimerkeissä on käytössä versio 1.28. Yhdistimien erolla on merkitystä. Versiossa 1.28 mcpToolDescription on pakollinen ja nimeämän tiedoston on oltava ZIP-tiedostossa. Versiossa 1.29 agentConnectors[]-merkinnät ovat vain URL-osoitteita ja mcpToolDescription on valinnainen, joten wiqd-luotu pakkaus ei koskaan aiheuta latausvirhettä. wiqd ei vielä luo yhdistimen todennuksen runkoa; se määritetään suoraan kohdassa Tuetut todennustyypit kuvatulla tavalla.

Vaihe 3: Tarkista muodostaminen aikana

Tee tarkistuksia jatkuvasti sen sijaan, että kokoaisit paketin ja toivoisit latauksen onnistuvan:

wiqd plugin validate
wiqd plugin validate --mode deep

validate on deklaratiivisen agenttipinnan staattinen offline-tarkistus. Jos laajennuksessa on vain taitoja tai vain yhdistimiä, mitään tarkistettavaa ei ole, mikä oli odotettavissa, sillä se tarkistaa vain koontisilmukan eikä muita vaiheita. validate --mode deep pakkaa ensin laajennuksen ja tarkistaa sitten muodostetun .zip:n samaa App Validation Librarya vasten, jota lataus käyttää. Tässä ASKILL-koodit ja yhdistinsäännöt tulevat esiin.

Suorita nämä kolme komentoa järjestyksessä:

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

Suorita ensin provision, sillä se kirjoittaa ympäristötiedoston, josta sekä package että share ovat riippuvaisia. --scope users mahdollistaa jakamiseen luettelossa olevien henkilöiden kanssa, kun taas --scope tenant mahdollistaa jakamisen kaikkien kanssa organisaatiossa. Kummassakin laajennus näkyy Jaettu kanssani -kohdassa, kun Cowork>Lähteet ja taidot>Laajennukset on valittu. Jos sen halutaan näkyvän sen sijaan Tutustu-osassa, järjestelmänvalvoja lataa paketin. Lisätietoja on kohdassa Vaihe 8: Julkaiseminen vuokraajaan. Voit poistaa sen, minkä provision loi, suorittamalla wiqd plugin delete --env local --yes.

Lähetys julkiseen kauppaan on edelleen manuaalinen prosessi Kumppanikeskuksessa. Lisätietoja on kohdassa Vaihe 9: Julkaiseminen julkisesti.

Laajennuksen vieminen toiseen isäntään

Jos taitoja käytetään Claude Codessa, Cursorissa tai muussa agentin taitoisännässä, projektin viedään sen sijaan, että kansiot kopioitaisiin käsin:

wiqd plugin export --format claude-plugin

export palaa oletusarvoon --format open-plugin, minkä lisäksi se hyväksyy myös arvon cursor-plugin. Se kirjoittaa pakkaamattoman hakemiston kohdassa <path>/export/<format>.

Aiemmin luodun laajennuksen tuominen

Jos käytössä on jo taidot ja MCP-palvelimet sisältävä Claude Code -laajennus, muuntoreittejä on kaksi. Valitsemasi reitti riippuu siitä, aiotko jatkaa laajennuksen kehittämistä vai vain toimittaa sen, mitä sinulla on.

Tavoite	Käytä
Laajennuksen kehittämisen, tarkistamisen ja lähettämisen jatkaminen Microsoft 365:ssä	`wiqd plugin import`
Julkaisukelpoisen `.zip`-tiedoston luonti heti aiemmin luodusta Claude-laajennuksesta	Muunnoskomentosarja

Tuonti wiqd:n avulla

wiqd plugin import tunnistaa lähteenä avoimen laajennuksen, Claude-laajennuksen tai Cursor-laajennukset ja tuottaa wiqd-laajennusprojektin siitä. Tuotu laajennus liittyy samaan elinkaareen kuin komennolla wiqd plugin create luotu laajennus:

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

--privacy-url ja --terms-url ovat pakollisia vain tuotaessa laajennus ensimmäistä kertaa. Jos lähteenä aiempi wiqd plugin export, edestakaiset metatiedot sisältää sen jo.

Tärkeää

Tuotu projekti tukee vain elinkaaren vain luku -osaa – wiqd plugin validate, show ja list. Sitä ei voi vielä pakata, valmistella tai jakaa, koska tuonti ei vielä luo näiden vaiheiden tarvitsemia paikallisia käyttöönottotiedostoja. Tämä on seurannassa oleva puute. Tarkista ajantasainen tila wiqd CLI -viitteestä. Jos julkaistavaa pakkausta tarvitaan heti, käytä muuntokomentosarjaa.

Muunna muuntokomentosarjan avulla

Muunnoskomentosarja kääntää Claude-laajennuksen suoraan julkaistavaksi M365-paketiksi:

Asenna CLI (edellyttää versiota 1.1.12 tai uudempaa):
```
npm install -g @microsoft/m365agentstoolkit-cli
```
Tarkista versio:
```
atk --version
```

Tuo lisäosa:

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

Komento lukee laajennuksen .claude-plugin/plugin.json (tai .cursor-plugin/plugin.json), .mcp.json ja skills/ hakemiston sekä luo sitten Agents Toolkit -projektin rungon, joka sisältää appPackage/manifest.json-tiedoston, taidot ja luodut kuvakkeet.

--privacy-url on --terms-url sisällytettävä, koska laajennuksen kokoonpanotiedoilla ei ole vastaavia kenttiä ja Microsoft 365 -kokoonpanotiedot edellyttävät molempia.

Note

atk import openplugin paikantaa kokoonpanotiedot pistettä etuliitteenä käyttävässä hakemistossa – .claude-plugin/plugin.json, .cursor-plugin/plugin.json tai .plugin/plugin.json – .mcp.json-tiedoston ohella. Agent Plugins 1.0.0 -määritys sijoittaa kokoonpanotiedot ylätason plugin.json-tiedostoon ja MCP-määrityksen mcp.json-tiedostoon. 1.0.0-asettelua noudattavaa laajennusta tuotaessa sen kokoonpanotiedot on siirrettävä .plugin/plugin.json-tiedostoon ja mcp.json-tiedoston nimeksi on vaihdettava .mcp.json.

Pakkaa tulos ladattavaksi .zip-tiedostoksi:

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 luo devPreview-kokoonpanotiedot. Muualla tässä artikkelissa käytetyissä kokoonpanotietoesimerkeissä on käytössä rakenne v1.28. Jos julkaiset kanavan kautta, joka edellyttää v1.28:aa, päivitä manifestVersion ja $schema luodussa appPackage/manifest.json.

Mitä tuodaan

Laajennusartefakti	M365-vastine	Huomautuksia
`.claude-plugin/plugin.json`	`manifest.json`	Nimi-, kuvaus- ja kehittäjäkentät yhdistetty; automaattisesti luotu GUID (deterministinen UUID v5)
`skills/*/SKILL.md`	`agentSkills[]`-merkinnät + `skills/`-kansio	Kopioitu sanatarkasti – identtinen muoto
`.mcp.json`-palvelimet	`agentConnectors[]` merkinnät	URL ja todennustyyppi tunnistettiin automaattisesti
`color.png` / `outline.png`	Pakkauksessa olevat kuvakkeet	Käytetään, jos olemassa; paikkamerkit luodaan, jos puuttuvat

Tärkeää

Jokaiselle kohteesta .mcp.jsontuodulle yhdistimelle luodaan authorization.referenceId paikkamerkki, joka on johdettu laajennuksesta ja palvelimen nimestä. Korvaa se todellisella OAuth-asiakkaan rekisteröintitunnuksella ennen julkaisemista. Lisätietoja on artikkelissa Tuetut todennustyypit.

Mitä ei muunneta

Seuraavia Claude-laajennuksen ominaisuuksia ei vielä tueta Microsoft 365 -manifestissa:

Claude-laajennuksen ominaisuus	Tila
`commands/` (kauttaviivakomennot)	Ei vielä tueta
`agents/` (aliagentit)	Ei vielä tueta
`hooks/` (tapahtumakäsittelijät)	Ei vielä tueta
`settings.json`	Ei sovellu
`bin/` (suoritettavat tiedostot)	Ei sovellu

Tuontiasetukset

Vaihtoehto	Kuvaus
`--path`, `-p`	Pakollinen. Laajennushakemisto, joka sisältää `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, tai `.plugin/plugin.json`
`--output`, `-o`	Kohdeprojektikansio (oletus: `./<plugin-name>`)
`--privacy-url`	`developer.privacyUrl` luoduille kokoonpanotiedoille
`--terms-url`	`developer.termsOfUseUrl` luoduille kokoonpanotiedoille
`--website-url`	`developer.websiteUrl`. Palautuu arvoon `homepage` ja sitten arvoon `author.url`
`--app-id`	Korvaa kokoonpanotietojen arvon `id` deterministisesti luodun UUID v5:n
`--default-auth-type`	`Auto` (oletus), `None`, `OAuthPluginVault` tai `ApiKeyPluginVault`

Todennustyypin automaattinen tunnistus:

Lähde	Oletusarvoinen todennustyyppi	Peruste
Ulkoiset HTTPS-URL:t	`OAuthPluginVault`	Useimmat etäohjelmointirajapinnat edellyttävät todennusta
`localhost` ja muut kuin HTTPS-URL-osoitteet	`None`	Paikalliset kehityspalvelimet

Jos automaattinen tunnistus ei vastaa asennusta, korvaa se komennolla --default-auth-type.

Vie takaisin laajennushakemistoon

Jos haluat siirtää Agents Toolkit -projektin takaisin laajennushakemistoon, esimerkiksi pitääksesi Claude Code -laajennuksen ja Cowork-paketin synkronoituina, käytä seuraavaa: atk export openplugin

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

Vaihtoehto	Kuvaus
`--path`, `-p`	Pakollinen. Agents Toolkit -projektikansio, joka sisältää `appPackage/manifest.json`
`--output`, `-o`	Kohdelaajennuksen hakemisto (oletus: `./<plugin-name>-openplugin`)
`--manifest-kind`	`open-plugin` (oletus, kirjoittaa `.plugin/plugin.json`), `claude-plugin` tai `cursor-plugin`

Vienti kirjoittaa x-microsoft-365-agents-toolkit-lohkon luotuun plugin.json-tiedostoon. Tämä lohko sisältää luettelotiedoston arvon id, kehittäjän URL-tunnisteet ja yhdistimen asetukset, joten edestakainen atk import openplugin ei tarvitse myöhemmin uudelleen arvoa --privacy-url tai --terms-url.

Note

x-microsoft-365-agents-toolkit-lohko koskee Agents Toolkitiä ja oletus-open-plugin kirjoittaa kokopanotiedot .plugin/plugin.json-tiedostoon. Agent Plugins 1.0.0 käyttää ylätason plugin.json-tiedostoa ja sisältää asiakasohjelmakohtaiset tiedot extensions-avaimessa yhdessä käänteisen toimialueen nimialueen kanssa, jolloin muut asiakasohjelmat ohittavat tämän lohkon sen sijaan, että toimisivat sen perusteella. Jos kohteena on Claude Code tai Cursor, ota käyttöön --manifest-kind claude-plugin tai cursor-plugin.

Vanha: PowerShell-muuntokomentosarja

Ennen atk-tuettua laajennuksen tuontia, muunnos käytti vain Windowsissa toimivaa PowerShell-komentosarjaa, joka on edelleen saatavilla -nimisenä muunnoskomentosarjana:

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

Käytä atk import openplugin sen sijaan. Se on ympäristöjen välinen, tukee sekä Cursor- että Claude Code -lähteitä ja voi viedä takaisin laajennushakemistoon.

Pakkaus kootaan käsin

Tämä osio on pakettimuodon viittaus: se kuvaa tarkalleen, mitä Build a plugin with wiqd luo, kenttä kerrallaan. Noudata sitä alusta loppuun, jos työkaluja ei voida asentaa tai jos oma pakkausputki muodostetaan. Käytä sitä viitteenä, jos haluat ymmärtää luodun paketin tai korjata siinä olevat virheet.

Vaihe 1: Luo ensimmäinen taitosi

Taito on SKILL.md-tiedoston sisältävässä kansiossa. Luo seuraava kansiorakenne:

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

Kirjoita SKILL.md käyttämällä YAML-etuosaa ja Markdown-tekstiä:

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

# Contract Analysis

## What This Skill Does

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

## Workflow

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

## Output Format

Present findings in a structured table:

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

SKILL.md:n metatietokentät

Pakolliset kentät:

Kenttä	Rajoitukset	Kuvaus
`name`	1–64 merkkiä, kebab-case-muoto	Taitotunniste - on vastattava kansion nimeä täsmälleen
`description`	1-1024 merkkiä	Taidon käyttöajankohta – käynnistinlauseisen sisällyttäminen

Tärkeää

Kansion nimen on vastattava edustan name-kenttää. Tämä ristiriita on yleisin taitojen epäonnistumisen syy.
Laajennusten description-luettelokenttiin ei saa sisältyä toimintokehotteita, jotka ohjaavat käyttäjät ostamaan tilauksia ulkoisiin Marketplace-sivustoihin.

Kansiopolku	`name` kenttä	Kelvollinen?	Miksi
`skills/contract-analysis/SKILL.md`	`contract-analysis`	Kyllä	Kansio ja nimi vastaavat
`skills/contract-analysis/SKILL.md`	`ContractAnalysis`	Ei	Nimi käyttää PascalCase-muotoa vastaavan kansion sijaan
`skills/my-skill/SKILL.md`	`contract-analysis`	Ei	Kansio on `my-skill` mutta nimi `contract-analysis`

Nimeämissäännöt (kebab-case): Käytä vain pienaakkosia, numeroita ja tavuviivoja. Älä käytä peräkkäisiä tavuviivoja äläkä alussa tai lopussa olevia tavuviivoja.

Esimerkki	Kelvollinen?	Ongelma
`bond-relative-value`	Kyllä	Pienet kirjaimet ja yhdysviivat
`fx-carry-trade`	Kyllä	Pienet kirjaimet ja yhdysviivat
`email`	Kyllä	Yksi sana, yhdysviivoja ei tarvita
`Bond_Relative_Value`	Ei	Alaviivat ja isot kirjaimet
`--my-skill--`	Ei	Alussa ja lopussa olevat yhdysmerkit
`my--skill`	Ei	Peräkkäiset yhdysmerkit

Vaihe 2: Lisää viitemateriaali (valinnainen)

Jos kyseessä on monimutkainen taito, pidä pääasiallinen SKILL.md siistinä ja siirrä yksityiskohtainen sisältö alihakemistoihin. Nämä ylimääräiset tiedostot ovat oheistiedostoja. Taito lataa ne tarvittaessa.

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

Kumppanitiedostojen rajoitukset

Kukin taito voi sisältää enintään 20 kumppanitiedostoa (mikä tahansa muu tiedosto kuin SKILL.md). Seuraavat rajoitukset ovat taitokohtaisia:

Limit	Arvo
Kumppanitiedostojen enimmäismäärä	20
Oheistiedoston enimmäiskoko	5 MB
Kumppanitiedostojen enimmäiskoko yhteensä	10 Mt
Latauksen aikakatkaisu (kaikki kumppanitiedostot)	15 sekuntia

Kumppanitiedostojen säännöt

Kumppanitiedostopoluissa on noudatettava seuraavia sääntöjä:

Käytä vain suhteellisia polkuja (ei absoluuttisia polkuja).
Ei polun läpikäyntiä (..-segmentit).
Tiedostonimissä ei saa olla käänteisiä vinoviivoja tai nollatavuja.
Ei piilotettuja tiedostoja (nimet, joiden alussa on .).
Ei Windowsille varattuja nimiä (CON, PRN, NUL, AUX, COM1–COM9, LPT1–LPT9).
Itse tiedostoa SKILL.md ei lasketa kumppanitiedostoksi.
Tiedostonimissä on käytettävä turvallisia merkkejä: aakkosnumeeriset merkit, yhdys- ja alaviivat, pisteet, välilyönnit sekä !.

Jotta kontekstiikkuna pysyy tehokkaana, järjestelmä lataa taitoja kolmessa tasossa:

Taso	Ladattaessa	Kohteen koko
Edusta (`name` + `description`)	Aina – käynnistyksen yhteydessä	~100 tunnusta
`SKILL.md` runko	Kun taito käynnistyy	Alle 5 000 tunnusta (1 500–2 000 sanaa)
Viitteet (`references/`)	Edustajan pyynnöstä	Rajoittamaton
Komentosarjat (`scripts/`)	Suoritettu, ei ladattu asiayhteyteen	Ei saatavilla

Viittaa alihakemistoihin eksplisiittisesti SKILL.md , jotta agentti tietää niiden olemassaolon:

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

Vaihe 3: Yhdistimen lisääminen (valinnainen)

Jos laajennuksen on käytettävä ulkoisia tietoja, lisää MCP-etäpalvelin. Tämä vaihe on valinnainen. Pelkkiä taitoja sisältävät paketit toimivat hyvin kehotepohjaisissa työnkuluissa.

Vinkki

Jos palvelin valvoo työkalun näkyvyyttä asiakasohjelman mukaan tai määrittelee saapuvan liikenteen, lisätietoja Coworkin esittämästä asiakasohjelman identiteetistä on kohdassa Palvelimeen suuntautuvan Cowork-liikenteen tunnistaminen.

Note

Mukautettuja laajennuksia ei tueta Cowork mobiililaitteessa.

Liittimen vaatimukset

Vaatimus	Yksityiskohtaiset tiedot
Liikenne	Suoratoistettava HTTP (HTTPS pakollinen, TLS 1.2+)
Protokolla	JSON-RPC 2.0 -viestimuoto
Työkalujen etsintä	Dynaamisen etsinnän `tools/list`-tuki (suositus)
Työkalun suoritus	`tools/call`-kutsun tuki
Saatavuus	Sovelluskaupassa julkaistujen sovellusten 99,9 %:n käytettävyyden palvelutasosopimussuositus
Vastausaika	Alle 30 sekuntia/työkalukutsu

Työkalujen suunnitteluohjeet

Yksi työkalu/toiminto pienissä ohjelmointirajapinnoissa (alle 15 toimintoa): search_case_law, get_ruling, cite_precedent
Haku ja suoritus suurissa ohjelmointirajapinnoissa (yli 50 toimintoa): search_actions + execute_action
Kuvaavat nimet: get_bond_price eikä getData
Monipuoliset syöterakenteet: Sisällytä kuvaus jokaiselle parametrille – agentti lukee tämän
Rakenteellinen tulos: Palauta JSON, jonka agentti voi muotoilla käyttäjää varten
Tiedostosyötteet: tiedosto hyväksytään käyttäjän työtilasta määrittämällä parametrin arvon contentEncoding: base64 avulla. Lisätietoja on kohdassa Tiedostojen vastaanottaminen Cowork-työtilasta.

Kuvaile yhdistimen työkaluja (`mcpToolDescription`)

remoteMcpServer-yhdistin voi valinnaisesti sisältää objektin mcpToolDescription. Jos annettu, sen sisäkkäinen file-ominaisuus osoittaa työkalukuvauksen JSON-tiedoston, joka pakataan .zip-ominaisuuteen ja johon pakkauksen juuren suhteellinen polku viittaa. Cowork löytää työkalut dynaamisesti MCP-palvelimeltasi eikä käytä tätä tiedostoa, vaikka se olisi läsnä.

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

Jos mcpToolDescription sisällytetään, viitattu tiedosto (esimerkiksi tools/contoso-legal-tools.json) kuvaa työkaluja, jotka yhdistin näyttää, ja sen on sisällyttävä ZIP-pakettiin. Se sisällytetään manifest.json- ja skills/-kansioiden ohella, kun laajennus pakataan.

Vinkki

Tämä vaatimus koskee manifestin versiota 1.28. wiqd plugin create:n luomat paketit on tarkoitettu versiolle 1.29, jossa agentConnectors[]-merkinnät sisältävät vain URL-osoitteen, mcpToolDescription on valinnainen eikä unohdettavaa työkalun kuvaustiedostoa ole.

Tuetut todennustyypit

Todennustyyppi	Milloin kannattaa käyttää 'ta	Käyttökokemus
`None`	Julkiset tai anonyymit ohjelmointirajapinnat, sisäiset palvelut	Läpinäkymätön – ei todennuskehotetta
`OAuthPluginVault`	OAuth 2.0 -rajapinnat (suositellaan tuotantokäyttöön)	Käyttäjä antaa OAuth-suostumuksen vain kerran
`ApiKeyPluginVault`	API-avaimeen perustuvat palvelut	Käyttäjä antaa avaimen kerran

Note

API-avaimen todentamisen tuki ei ole vielä käytettävissä Coworkissa.
Jos MCP-palvelimesi vaatii API-avaimen, käytä sen sijaan OAuthPluginVault:aa tai dynaamista asiakasrekisteröintiä tai tarjoa päätepiste, joka hyväksyy None.

OAuthPluginVault- ja ApiKeyPluginVault-ominaisuuksissa referenceId osoittaa Microsoft Enterprise -tunnuskauppaan tallennettuihin tunnistetietoihin; salaisuudet eivät näy koskaan kokoonpanotieto- tai taitotiedostoissa. Arvo referenceId on OAuth-asiakkaan rekisteröintitunnus, jonka luot, kun rekisteröit OAuth-asiakkaan Agents Toolkitin avulla.

Tärkeää

Määritä OAuth-asiakasohjelmaa rekisteröitäessä organisaatiokohtaisen käyttöasteen organisaatioksi Mikä tahansa Microsoft 365 -organisaatio; tämä varmistaa, että laajennus toimii kaikissa vuokraajissa.

MCP:n todennus

Lisätietoja OAuthin tai ApiKeyn käytöstä todennuksessa sekä niiden määrittämisestä ja määrityksistä on kohdassa Microsoft 365 Copilotin agenttien MCP- ja ohjelmointirajapintalaajennusten todennuksen määrittäminen.

Dynaaminen asiakasrekisteröinti

Jos MCP-palvelin tukee dynaamista asiakasrekisteröintiä, authentication-määritys voidaan jättää pois yhdistinmääritelmästä ja Cowork luo OAuth-asiakasohjelman automaattisesti laajennuksen puolesta.

Note

authentication-määrityksen pois jättäminen on tuettu vain Coworkissa. Sitä ei tueta Copilot Chatissa. Jos laajennuksen on toimittava myös Copilot Chatissa, määritä OAuthPluginVault todennus Tuetut todennustyypit -kohdassa kuvatulla tavalla.

Voit jättää objektin authorization kokonaan pois. Määritä MCP-palvelimen URL-osoite, niin Cowork huolehtii OAuth-asiakkaasta:

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

Vaihe 4: Luo manifesti

Luo manifest.json paketin juureen. Esimerkissä käytetään manifestiversiota 1.28; wiqd plugin create määrittää sen sijaan version 1.29, jossa liitintietueet sisältävät vain URL-osoitteen.

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

Yhdistintä liitettäessä agentConnectors on sisällytettävä:

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

Yhdistimen määrityksessä referenceId-arvon on oltava OAuth-rekisteröintitunnus. Jos sisällytät mcpToolDescription, sen file on viitattava ZIP-pakettiin sisältyvään työkalun kuvaus-JSON-tiedostoon.

Tärkeää

Version 1.28 manifestin skeema on tiukka: se asettaa additionalProperties: false juureen, joten kaikki kentät, joita ei ole määritetty skeemassa, hylätään. Kentät, jotka ovat kelvollisia Teams-sovelluksen vakiomanifesteissa, kuten packageName, aiheuttavat latauksen epäonnistumisen virheellä, kuten Property 'packageName' has not been defined and the schema does not allow additional properties. Sisällytä vain tässä näkyvät kentät.

Vaihe 5: Kuvakkeiden lisääminen

Luo kaksi PNG-kuvaketta:

Kuvake	Koko	Purpose
`color.png`	192×192 pikseliä	Värillinen sovelluskuvake kaupassa ja sovellusluettelossa
`outline.png`	32×32 pikseliä	Yksivärinen ääriviiva-kuvake suppeissa näkymissä

Jos kuvakkeita ei vielä ole, atk import openplugin luo värilliset paikkamerkit. Korvaa ne ennen myymälään lähettämistä.

Vaihe 6: Pakkaus

Luo ZIP-tiedosto, jonka koko sisältö on juuritasolla. (wiqd plugin package tuottaa saman rakenteen ominaisuuden wiqd plugin provision jälkeen.)

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

Jos yhdistimeen sisältyy mcpToolDescription, sisällytä työkalun kuvauksen JSON-tiedosto, johon se viittaa. Paketit, jotka eivät käytä mcpToolDescription:ta, mukaan lukien vain taitoja sisältävät paketit, eivät tarvitse tools/-kansiota.

Windows (PowerShell):

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

macOS/Linux:

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

Microsoft 365 Agents Toolkitin käyttäminen

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

Vaihe 7: Testaa

Testaa sovellusta lataa sovelluspaketti Teamsiin kohdassa Sovelluksen lataaminen Teamsiin kuvatulla tavalla.

Jos laajennuksen muodostamisessa on käytössä wiqd, suorita sen sijaan wiqd plugin provision; se rekisteröi laajennuksen vuokraajaan puolestasi. Käsin koottu paketti voidaan testata itse tekemällä sovelluksen rinnakkaislataus Microsoft 365 Agents Toolkit -komentorivikäyttöliittymässä:

Asenna @microsoft/m365agentstoolkit-cli kohdasta npm:
```
npm install -g @microsoft/m365agentstoolkit-cli
```
Tarkista asennus suorittamalla seuraava komento:
```
atk --version
```
Käytä todennukseen Microsoft 365 -työtiliä:
```
atk auth login
```
Kirjaudu työtilille ja asenna agenttipaketti. Korvaa tiedostopolku ZIP-paketin sijainnilla:
```
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
```
Jos asennus onnistuu, palautetussa tuloksessa on tilin TitleId ja AppId.
Tallenna tunnukset myöhempää käyttöä varten, kun päivität tai poistat asennuksen.

Lisätietoja on artikkelissa Microsoft 365 Agents Toolkit command line interface.

Vaihe 8: Julkaiseminen vuokraajaan

Aseta laajennus luetteloon Tutustu-osassa lataamalla paketti hallintakeskuksessa; kuka tahansa organisaatiossa löytää sen sieltä:

Avaa M365-hallintakeskus>Hallitse sovelluksia>Lataa mukautettu sovellus.
Valitse kolme pistettä -painike (...) >Lisää agentti.
Lataa .zip-paketti.
Avaa Cowork>Lähteet ja taidot>Laajennukset. Laajennuksesi näkyy Discover-osiossa.

wiqd plugin share sijoittaa laajennuksen Jaettu kanssani -osaan eikä Tutustu-osaan. Käytä sitä testaukseen ja kohdennettuun käyttöönottoon tietyille käyttäjille. Kun laajennus on ladattu hallintakeskukseen, siitä tulee löydettävä.

Vaihe 9: Julkaiseminen yleisölle

Jos laajennus on tarkoitettu julkisesti jaettavaksi, laajennus lähetetään Microsoft 365 App Storeen kumppanikeskuksen kautta. Lisätietoja on kohdassa Microsoft 365 Copilotin agenttien julkaiseminen.

Yhdistimen testaaminen paikallista MCP-palvelinta vastaan

Yhdistimissä tarvitaan HTTPS mcpServerUrl. Koneessa suoritettavan palvelimen testaaminen edellyttää, että sen on oltava näkyvissä julkisena HTTPS-URL-osoitteena. Kehitystunnelit tarjoavat välityksen, joka terminoi TLS:n puolestasi.

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

Tärkeää

Käytä --protocol http, ei https. --protocol-merkintä kuvaa paikallisen palvelun, johon tunneli ohjaa eikä julkisen tunnelin URL-osoitetta. Useimmat paikalliset MCP-palvelimet puhuvat pelkkää HTTP-protokollaa, joten jos määrität --protocol https palvelimen palvellessa HTTP:tä, jokainen tunnelin kautta suoritettava pyyntö palauttaa 502 virheen. Välityspalvelu päättää TLS-protokollan ja toimii julkisena HTTPS-URL-osoitteena tästä merkinnästä riippumatta.

Vianetsintä

Symptom	Syy	Korjaa
Jokainen tunneloitu pyyntö palauttaa `502` ja paikallinen palvelin puhuu HTTP:tä	`devtunnel port create` suoritettiin ominaisuuden `--protocol https` avulla	Portin uudelleenluonnissa on käytössä `--protocol http`
Tunneloidut pyynnöt palauttavat arvon `502` macOS:ssä, vaikka paikallinen palvelin on käynnissä	Palvelin on sidottu arvoon `0.0.0.0` (vain IPv4), mutta tunnelin valinta on `localhost`, joka ratkaisee ensin arvon `::1` (IPv6)	Sido palvelin `::` niin, että se hyväksyy sekä IPv4- että IPv6-yhteydet
Lataus epäonnistuu, viestinä `Property '<field>' has not been defined and the schema does not allow additional properties`	Luettelo sisältää kentän, jota v1.28-rakenne ei salli (esimerkiksi `packageName`)	Poista kenttä; V1.28-rakenne käyttää `additionalProperties: false`

Pakkausmallit

Valitse laajennukseen sopiva malli:

Vain taidot (ei yhdistintä)

Sopii parhaiten kehotepohjaisiin työnkulkuihin, asiakirja-analyysiin ja kirjoitusapuun.

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

Taidot ja etäyhdistin

Soveltuu parhaiten tietojen analysointiin, ohjelmointirajapintaintegraatioihin ja yritysjärjestelmiin.

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

Vain yhdistin (ei mukautettuja taitoja)

Käytä tätä vaihtoehtoa tietolähteille, joita Cowork:n sisäänrakennetut taidot voivat jo käyttää.

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

Tuotu Claude Code- tai Cursor-laajennus

Käytä tätä vaihtoehtoa olemassa oleville Claude-ekosysteemilaajennuksille, jotka on kohdistettu Coworkiin. Jos haluat jatkaa laajennuksen kehittämistä Microsoft 365:ssä, tuo se:

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

Jos haluat tuottaa laajennuksesta julkaistavan .zip sellaisena kuin se on nykyään, käytä muunnoskomentosarjaa:

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

Taitojen laatimisen parhaat käytännöt

Näiden ohjeiden avulla voit luoda taitoja, jotka aktivoituvat luotettavasti ja tuottavat johdonmukaisia tuloksia.

Tehokkaiden kuvausten kirjoittaminen

description-kenttä määrittää, milloin agentti aktivoi taidon. Ole täsmällinen:

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

Luo tehokkaita työnkulkuja

Ole tarkka kuvauksessa. Sisällytä käynnistinlauseet: "Käytä, kun käyttäjä pyytää..." Tämä kuvaus ilmaisee, miten agentti päättää aktivoitavan taidon.
Rakenne työnkulkuna. Numeroi vaiheet. Kunkin vaiheen tulisi liittyä konkreettiseen toimintoon (tiedoston lukeminen, työkalun kutsuminen, tulosteen luominen).
Tulosmuodon määrittäminen. Näytä täsmälleen se taulukko, luettelo tai asiakirjarakenne, jota käyttäjien on odotettava. Tämä määritelmä parantaa johdonmukaisuutta huomattavasti.
Viitetyökalut nimen mukaan. Jos taito on riippuvainen yhdistintyökaluista, nimeä ne selkeästi: "Työkalulla search_case_law tehdään..."
Pidä varsinainen SKILL.md kevyenä. Siirrä määritetyt viitemateriaalit references/-alihakemistoon. Taidon tekstinosan on oltava työnkulku eikä tietosanakirja.

Vältä yleisiä virheitä

Salaisuuksia ei upotetaSKILL.md-tiedostoihin. Ota agentConnectors käyttöön ohjelmointirajapinnan tunnistetietojen todennukseen.
Sisäänrakennettujen taitojen kaksoiskappaleita ei tehdä. Tarkista sisäänrakennettu taitoluettelo ennen muodostamista.
Älä tee osaamisesta liian laajaa. "Tee kaikki juridisiin asiakirjoihin liittyvä" on huonompi vaihtoehto kuin sopimusanalyysia, lausekkeen poimintaa tai juridista tutkimustyötä koskevat erityistaidot.
Älä kovakoodaa tiedostopolkuja tai järjestelmäkomentoja. Taitojen on oltava siirrettävissä ympäristöjen välillä.
Kaikkea ei saa sisällyttää SKILL.md-tiedostoon. Jos tekstin runko ylittää ~3 000 sanaa, siirrä yksityiskohtainen sisältö kohteeseen references/.

Kelpoisuussäännöt

Kun lähetät pakettisi, alusta tarkistaa sen useilla tasoilla. Korjaa nämä virheet ennen lähettämistä, jotta vältät hylkäämisen.

Jos haluat havaita ne rakentamisen aikana lataushetken sijaan, suorita wiqd plugin validate --mode deep. Tämä komento pakkaa laajennuksen ja suorittaa samat säännöt paikallisesti. Lisätietoja on kohdassa Vaihe 3: Tarkista työn edetessä.

Kokoonpanotietotason tarkistus

Koodi	Sääntö	Vakavuus
ASKILL-M001	`folder` on pakollinen jokaisessa `agentSkills`-kohteessa	Error
ASKILL-M002	`agentSkills` taulukossa voi olla enintään 20 alkiota	Error
ASKILL-M003	`folder` polussa voi olla enintään 256 merkkiä	Error

Pakettitason validointi

Koodi	Sääntö	Yleinen korjaus	Vakavuus
ASKILL-P001	Kokoonpanotietojen viittaama kansio on ZIP-tiedostossa	Tarkista ZIP-rakenne	Error
ASKILL-P002	Kansiossa on `SKILL.md` tiedosto	Lisää puuttuva `SKILL.md`	Error
ASKILL-P003	`SKILL.md`-tiedossa on kelvollinen YAML-edusta `---`-erottimien välissä	YAML-syntaksin korjaaminen	Error
ASKILL-P004	Frontmatter sisältää `name` kentän	Lisää `name:` alkutietoihin	Error
ASKILL-P005	Frontmatter sisältää `description` kentän	Lisää `description:` alkutietoihin	Error
ASKILL-P006	`name` vastaa kansion nimeä (polun viimeinen segmentti)	Nimeä kansio uudelleen tai korjaa `name:`	Error
ASKILL-P007	`name` on kebab-case	Käytä `my-skill`, älä `MySkill` tai `my_skill`	Error
ASKILL-P008	Taulukossa ei ole päällekkäisiä `folder` arvoja	Poista kaksoiskappaleet	Error

Yhdistimen validointi

Sääntö	Vakavuus
Kuhunkin yhdistimeen tarvitaan `id` ja `displayName`	Error
Kaikkien yhdistimien `id` arvojen on oltava yksilöllisiä manifestissa	Error
Täsmälleen yksi `plugin` tai `remoteMcpServer`	Error
`mcpServerUrl` on oltava kelvollinen HTTPS URL	Error
Jos `mcpToolDescription` se löytyy, sen `file` on oltava ZIP-tiedostossa	Error
`authorization.referenceId` Pakollinen, ellei tyyppi ole `None`	Error
`authorization.referenceId` ei saa olla läsnä, kun tyyppi on `None`	Error

Oheistiedoston tarkistus

Portaali tarkistaa oheistiedostot (viitemateriaalit, komentosarjat ja muut tiedostot SKILL.md:n mukana) lataamisen ja synkronoinnin yhteydessä:

Sääntö	Vakavuus
Enintään 20 taitokohtaista kumppanitiedostoa (pois lukien `SKILL.md`)	Error
Kunkin kumppanitiedoston on oltava kooltaan enintään 5 Mt	Error
Kumppanitiedostojen taitokohtaisen kokonaiskoon on oltava enintään 10 Mt.	Error
Tiedostopolkujen on oltava suhteellisia (ei absoluuttisia polkuja)	Error
Ei hakemistosiirtymäsegmenttejä (`..`)	Error
Ei kenoviivoja tai nollatavuja tiedostonimissä	Error
Ei piilotettuja tiedostoja (nimet, joiden alussa on `.`)	Error
Ei Windowsille varattuja nimiä (`NUL`, `COM1`, `COM9`, `LPT9`, `LPT1`–`AUX`, `PRN`–`CON`)	Error
Tiedostonimissä on käytettävä vain turvallisia merkkejä (aakkosnumeerisia merkkejä, yhdysmerkkejä, alaviivoja, pisteitä, välilyöntejä, jne. `!`)	Error

Käyttöympäristöjen välinen yhteensopivuus

Taidot käyttävät Agent Skills -avointa standardia. Samat SKILL.md tiedostot toimivat useissa tekoälytyökaluissa:

Platform	Yhteensopivuus
Claude Code	Täsmälleen sama `SKILL.md`-muoto
Claude.ai-projektit	Taidot voidaan ladata kokonaisina projektitiedostoina
VS Code/ GitHub Copilot	Agentin kaikkia tietoja tuetaan agenttitilassa
Gemini CLI	Agentin kaikkia taitoja tuetaan
JetBrains Junie	Agentin kaikkia taitoja tuetaan
OpenAI Codex	Agentin kaikkia taitoja tuetaan
Kursori	Agentin kaikkia taitoja tuetaan

Jos sekä Claude Code- että Copilot Cowork -taitoja kehitetään, laadi laajennus wiqd:n avulla. Tuote Claude Code -asettelu sitten suorittamalla wiqd plugin export --format claude-plugin. Jos aloitetaan mieluummin Claude Code -laajennusrakenteesta, joka on yläjoukko, asettelu on seuraava:

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)

Se tuodaan sitten Microsoft 365:een, kun ollaan valmiita julkaisemaan Microsoft 365 App Storeen, käyttämällä joko komentoa wiqd plugin import tai muunnoskomentosarjaa:

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

MCP-merkintöjen ja vahvistusten hallinta

Copilot Cowork lukee MCP-vakio-objektin annotations työkaluissa, jotka palvelin palauttaa ominaisuudesta tools/list, ja päättää sen avulla, tarvitseeko työkalukutsu käyttäjän vahvistusta ja mikä selite näytetään kehotteessa.

Käytettävissä olevat kentät

Kenttä	Kirjoita	Vaikutus
`readOnlyHint`	bool	`false`: Vahvistus vaaditaan ennen työkalun käynnistymistä.
`destructiveHint`	bool	`true`: Vahvistus vaaditaan ennen työkalun käynnistymistä.
`title`	merkkijono	Vahvistusvalintaikkunassa näkyvä ihmisluettava selite. Palautuu työkalun nimeen, jos sitä ei ole.

Vahvistussäännöt

Vahvistus vaaditaan, jos readOnlyHint == false tai destructiveHint == true.

Kaikissa työkaluissa on oltava turvallisuusmerkinnät. Työkaluja, joissa ei ole merkintöjä, käsitellään tuhoisina ja ne edellyttävät vahvistusta. Lisätietoja on kohdassa MCP-rakenneviite.

MCP-esimerkkejä

Tuhoava toiminto ja lyhyt selite:

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

Automaattisesti suoritettava turvallinen luku:

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

Mitä on saatavilla nyt

Microsoft-työkalut (Graph, Dataverse ja muut), joita Coworkin sisäänrakennettu rajoittaa huomautuksista huolimatta.
Muissa kuin Microsoftin MCP-palvelimissa annotaatioihin perustuva vahvistus otetaan käyttöön asteittain. Vihjeiden määrittäminen on nyt yhteensopiva myös jatkossa, ja vahvistuskehotteet tulevat näkyviin käyttöönoton laajentuessa ilman kehittäjän tekemiä muutoksia.

Tiedostojen hyväksyminen Cowork-työtilasta

Yhdistämistyökalu voi ottaa syötteenä tiedoston käyttäjän Cowork-istunnosta – käyttäjän liittämän asiakirjan, Cowork tallensiman sähköpostiliitteen tai aiemmassa vaiheessa luodun tiedoston. Määritä parametri vakio-JSON Schema -avainsanalla contentEncoding: base64 ja Cowork käsittelee loput. Microsoft-kohtaista rakennelaajennusta ei tarvita eikä palvelimen ohjelmointirajapinnan ulkoasu muutu.

Cowork ratkaisee työtilatiedoston ja base64-koodaa sen ennen palvelimen kutsumista, joten tiedostotavut eivät koskaan siirry agentin kontekstiin. Agentti vain näkee ja lähettää vain työtilan tiedostopolut.

Note

Älä pyydä agenttia käyttämään base64-koodausta itse tiedostossa ja liittämään blob-objektia työkalukutsuun. Tämä lähestymistapa lataa koko tiedoston mallin kontekstiin ja riippuu siitä, että malli toistaa blobin täsmälleen. Se näyttää toimivan pienissä testitiedostoissa ja epäonnistuvan oikeissa tiedostoissa.

Tiedostoparametrin määritteleminen

Merkkijono-ominaisuus, jossa on contentEncoding: base64, tunnistetaan tiedostosyötteeksi:

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

Myös kyseisten merkkijonojen matriisi tunnistetaan työkaluissa, jotka hyväksyvät useita tiedostoja:

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

Mitä agentti näkee

Jos tiedostoparametrit määritetään inputSchema.properties-ylätasolla, Cowork korvaa ne mallin käytettävissä olevassa rakenteessa yhdellä direct_attachment_file_paths-matriisilla; kyseessä on sama parametri, jota Coworkin sisäänrakennetut työkalut käyttävät, joten agentti tietää jo, miten se täytetään. Yllä oleva skeema esitetään agentille seuraavasti:

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

Jos työkalu määrittää useita ylätason tiedostoparametreja, ne kaikki tiivistetään yhdeksi direct_attachment_file_paths-matriisiksi. Cowork levittää ratkaistut tiedostot kutsun aikana takaisin alkuperäisiin parametrinimiin määritysjärjestyksessä.

Sisäkkäiset tiedostoparametrit

Agentti tukee tiedostoparametria, joka on upotettuna objektin tai objektimatriisin sisälle Agentti käsittelee tämän parametrin eri tavalla: tiivistämisen sijaan agentti kirjoittaa sen paikalleen polkumerkkijonoon omassa sijainnissa. Tämä lähestymistapa säilyttää yhteyden tiedoston ja sen rinnakkaiskenttien välillä. Saat esimerkiksi yhden kuitin kuluriviä kohti:

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

Agentti täyttää parametriin line_items[].receipt työtilan polun ja Cowork vaihtaa kunkin base64-sisällön polun ennen kutsun välittämistä.

Sisäkkäisyys kulkee neljän tasosyvyyden läpi inputSchema-ylätason alapuolella. $ref-osoittimia ei seurata – määritä tiedostoparametrissa eikä $ref-parametrissa.

Mitä palvelimesi vastaanottaa?

Palvelimesi vastaanottaa tavallisen tools/call:n, jossa alkuperäiset parametrien nimet on täytetty base64-koodatulla sisällöllä:

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

Palvelimen ei tarvitse tietää, että agentti käytti polkupohjaista liittymää, eikä se vaikuta työkaluihin, jotka eivät määritä contentEncoding: base64 parametreja.

Rajoitukset

Limit	Arvo
Tiedostoja työkalukutsua kohti	8
Tiedostokohtainen koko	150 MiB
Työkalukutsun kokonaiskoko	150 MiB
Työkalukohtaiset matriisitiedoston parametrit	1 (yhdistä se mihin tahansa määrään skalaaritiedostoparametreja)
Suurin sisäkkäisyyssyvyys	4 tasoa ylimmän tason alapuolella `inputSchema`

Kutsu, joka ylittää tiedostojen määrän tai kokorajoituksen, epäonnistuu työkaluvirheellä eikä se koskaan päädy palvelimellesi. Ota 150 MiB -enimmäiskoko huomioon ohjelmointirajapinnan ja sen aikakatkaisujen koossa: base64 paisuttaa tietoja noin kolmanneksella raakatiedoston kokoon verrattuna ja koodattu sisältö lähetetään JSON-RPC-muotoisena pyyntönä.

Suositukset

Kuvaile parametria ihmislukijalle. Agentti määrittää kuvauksen perusteella, mikä tiedosto liittyy mihinkin parametriin. Esimerkiksi "The signed contract PDF to analyze" toimii paremmin kuin "file".
Ilmoita hyväksymäsi muodot parametrin kuvauksessa. Cowork välittää eteenpäin kaiken, mitä käyttäjä liittää. Vahvista sisältötyyppi omalla puolella ja palauta selkeä työkaluvirhe, jos se ei ole käyttökelpoinen.
Määritä huomautukset. Työkalu, joka vastaanottaa tiedoston ja käsittelee sen, ei yleensä ole vain luku -tilassa, joten se pyytää vahvistusta. Lisätietoja on kohdassa MCP-huomautukset ja vahvistusten hallinta.
Pidä tiedostoparametrit samalla rivillä. $ref-arvossa olevaa parametria tai neljää tasoa syvemmällä olevaa parametria ei uudelleenkirjoiteta. Palvelimesi vastaanottaa polkumerkkijonon siellä, missä se odottaa sisältöä.
Määritä enintään yksi taulukkotiedostoparametri työkalua kohti. Jos tiedostoja on vähintään kaksi, Cowork ei tiedä, mikä tiedosto kuuluu mihinkin matriisiin ja kutsu epäonnistuu työkaluvirheen vuoksi. Käytä yhtä matriisia tai useita skalaariparametreja taikka skalaarien ja yhden matriisin yhdistelmää.
Tarkka määrä on odotettavissa vain skalaarityökaluissa. Jos työkalu ilmoittaa vain skalaaritiedostoparametreja, agentin välittämien tiedostojen määrän on vastattava ilmoitettujen parametrien määrää. Merkitse valinnaiset tiedostoparametrit selkeästi kuvauksissa, mikä estää agentin ali- tai ylitarjonnan.

Note

Tämä mekanismi edeltää Model Context Protocolin omaa tiedostosyöttötyötä, jota MCP File Uploads Working Group standardoi. Cowork saattaa lisätä tuen deklaratiivisten tiedostosyötteiden standardoidulle muodolle, kun se tulee saataville. contentEncoding: base64 Tässä kuvattu sopimus on edelleen voimassa.

Tunnista palvelimellesi tuleva Cowork-liikenne

Jos MCP-palvelin valvoo työkalun asiakaskohtaista näkyvyyttä tai jos vastaanotettava liikenne halutaan määrittää, Coworkista tulevat pyynnöt voidaan tunnistaa. Cowork esittelee vakaan ohjelmistoidentiteetin kahdella kanavalla:

Kanava	Missä se näkyy	Arvo
`User-Agent` pyynnön otsikko	Jokainen lähtevä pyyntö, jonka Cowork lähettää palvelimellesi	`copilot-cowork/1.0`
`clientInfo` MCP `initialize` -kättelyssä	Vain `initialize`-pyyntö	`{ "name": "copilot-cowork", "version": "<version>" }`

`copilot-cowork`-etuliitetäsmäytys

Täsmäytyksenä copilot-cowork-etuliite, jossa kirjainkoolla ei ole merkitystä, jommassakummassa kanavassa. Älä käytä täsmäytykseen täsmällistä copilot-cowork/1.0-merkkijonoa tai tiettyä ominaisuutta clientInfo.version. Versio seuraa asiakasohjelman käyttäjätietosopimusta ja sen odotetaan muuttuvan; etuliitevastine pitää portin toiminnassa versiolisäyksissä.

# Correct: case-insensitive prefix match
copilot-cowork

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

Oikean kanavan valinta porttiin

Kahdella kanavalla on eri laajuudet, joten valinta tehdään sen mukaan, kumpi vastaa palvelimen tapaa valvoa porttia:

Otsake User-Agent on mukana jokaisessa pyynnössä, mukaan lukien tools/list ja tools/call Jos valvonta tai määrite on pyyntökohtainen, käytä tätä otsikkoa vastaavaa versiota.
clientInfo lähetetään vaininitialize kättelyssä. Jos käyttöä rajoitetaan istuntokohtaisesti yhteyden muodostamisen yhteydessä, voit lukea sen silloin, mutta sitä ei toisteta myöhemmissä pyynnöissä.

Mitä identiteetti sisältää ja ei sisällä

Identiteetti nimeää vain ohjelmiston. Se on sama kaikille Cowork-käyttäjille ja -yhteyksille, eikä se koskaan välitä käyttäjän käyttäjätietoja. Käyttäjätiedot pysyvät yhdistimen todennusmäärityksen määrittämässä valtuutustyönkulussa.

Identiteetti sisältää	Identiteettiin ei sisälly
Vakaa ohjelmiston nimi (`copilot-cowork`) ja sopimusversio	Mikä tahansa vuokraajan, käyttäjän, istunnon tai keskustelun tunniste
Sama arvo jokaisessa pyynnössä ja jokaisessa yhteydessä	Yhdistinkohtainen tarkenne

Koska yhdistinkohtaista tarkennetta ei ole, kyseisen käyttäjätiedon avulla ei voi tällä hetkellä ilmaista, mikä yhdistin tekee kutsun, tai erottaa julkaistua Microsoft-laajennusta samaan URL-osoitteeseen osoittavasta oheisladatusta palvelimesta. Jos tällaista erottelu tarvitaan, valvo sen käyttöä yhdistimen valtuutusmäärityksen eikä asiakasohjelman käyttäjätietojen kautta.

Yleisiä kysymyksiä

Voinko käyttää M365-paketin skills-toimintoja Claude Codessa?

Kyllä. Taitokansiot sisältävät agentin vakiotaidot. Suorita wiqd plugin export --format claude-plugin luodaksesi Claude Code -hakemistorakenteen, tai kopioi skill-kansiot kohteeseen .claude/skills/ missä tahansa Claude Code -projektissa.

Tarvitsenko etäliittimen?

Nro Pelkkiä taitoja sisältävät paketit toimivat hyvin kehotepohjaisissa työnkuluissa. Yhdistimiä tarvitaan vain silloin, kun taito tarvitsee reaaliaikaisia tietoja ulkoisesta järjestelmästä.

Miten laajennuksen taidot eroavat sisäänrakennetuista taidoista?

Laajennuksen taidot ja lähteen "package" näkyvät ohjelmointirajapinnassa. Ne eivät voi ohittaa samannimisiä valmiita taitoja. Järjestelmänvalvojan käyttöönottamissa paketeissa näkyy isAdminDeployed: true.

Voivatko IT-järjestelmänvalvojat hallita laajennusten saatavuutta?

Kyllä. M365:n vakiomuotoisia hallintakäytäntöjä käytetään: vuokraajatason sallittujen luettelot ja estoluettelot, järjestelmänvalvojan hallitsemat käyttöönotot ja vaatimustenmukaisuuskäytännöt.

Mitä tapahtuu, jos laajennus kumotaan?

Kyseisen paketin taidot ja liittimet poistetaan käyttäjän istunnosta seuraavassa synkronointijaksossa. Aktiivisia keskusteluja ei keskeytetä, mutta uusissa istunnoissa ei ole paketin ominaisuuksia.

Mikä on enimmäismäärä taitoja pakettia kohden?

Kaksikymmentä (20) taitoa (ASKILL-M002:n mukaan). Yhdistimien kohdalla raja on 10 pakettia kohden.

Voivatko taidot viitata saman paketin yhdistintyökaluihin?

Kyllä, ja heidän pitäisi. Nimeä työkalut eksplisiittisesti SKILL.md-työnkulussa (esimerkiksi Tee työkalun search_case_law avulla...). Agentti yhdistää ne suorituksen aikana.

Voivatko laajennuksen työkalut hyväksyä tiedostoja Cowork-työtilasta?

Kyllä. Määritä työkaluparametri arvon contentEncoding: base64 avulla, niin Cowork ratkaisee käyttäjän työtilatiedoston base64-sisällöksi ennen palvelimen kutsumista. Malli välittää tiedostopolkuja, ei tiedoston sisältöä, joten suuret tiedostot eivät kuluta mallin kontekstia. Lisätietoja määrittelystä ja rajoituksista on kohdassa Tiedostojen hyväksyminen Cowork-työtilasta.

Miten luon paketilleni deterministisen GUID:n?

wiqd plugin create luo ja kiinnittää sovellustunnuksen puolestasi. Muuntokomentosarjassa on käytössä laajennuksen nimen UUID v5 (SHA-1-pohjainen), joten muunnoksen suorittaminen kahdesti tuottaa saman GUID-tunnuksen. Käytä manuaaliseen pakkaamiseen mitä tahansa GUID-muodostinta. Varmista, että se pysyy vakaana eri versioissa.

Mihin manifestiversioon minun kannattaa kohdistaa?

Käytä versiota 1.29, jos muodostuksessa on käytössä wiqd, joka kiinnittää sen puolestasi. Versiossa 1.29 agentConnectors[]-merkinnät ovat vain URL-osoitteita ja mcpToolDescription on valinnainen. Tämä artikkelin käsin laadituissa esimerkeissä käytetään versiota 1.28, jossa mcpToolDescription on pakollinen ja sen nimeämän tiedoston on oltava ZIP-tiedostossa. atk import openplugin käyttää versiota UUID v5 (SHA-1-pohjainen) laajennuksen nimestä. Tuonnin suorittaminen kahdesti tuottaa saman GUID-tunnuksen. Oma määritetään välittämällä --app-id. Käytä manuaaliseen pakkaamiseen mitä tahansa GUID-muodostinta. Varmista, että se pysyy vakaana eri versioissa.

Palaute

Onko tästä sivusta apua?

Viimeksi päivitetty 2026-10-30

Copilot Coworkin laajennusten muodostaminen

Koostettu sisältö

Aloituskohdan valinta

Laajennuksen muodostaminen wiqd:n avulla

Vaihe 1: Asenna wiqd ja kirjaudu sisään

Vaihe 2: Luo laajennuksen runko ja lisää ominaisuudet

Vaihe 3: Tarkista muodostaminen aikana

Vaihe 4: Valmiste, paketoi ja jaa

Laajennuksen vieminen toiseen isäntään

Aiemmin luodun laajennuksen tuominen

Tuonti wiqd:n avulla

Muunna muuntokomentosarjan avulla

Mitä tuodaan

Mitä ei muunneta

Tuontiasetukset

Vie takaisin laajennushakemistoon

Vanha: PowerShell-muuntokomentosarja

Pakkaus kootaan käsin

Vaihe 1: Luo ensimmäinen taitosi

SKILL.md:n metatietokentät

Vaihe 2: Lisää viitemateriaali (valinnainen)

Kumppanitiedostojen rajoitukset

Kumppanitiedostojen säännöt

Vaihe 3: Yhdistimen lisääminen (valinnainen)

Liittimen vaatimukset

Työkalujen suunnitteluohjeet

Kuvaile yhdistimen työkaluja (mcpToolDescription)

Tuetut todennustyypit

MCP:n todennus

Dynaaminen asiakasrekisteröinti

Vaihe 4: Luo manifesti

Vaihe 5: Kuvakkeiden lisääminen

Vaihe 6: Pakkaus

Vaihe 7: Testaa

Vaihe 8: Julkaiseminen vuokraajaan

Vaihe 9: Julkaiseminen yleisölle

Yhdistimen testaaminen paikallista MCP-palvelinta vastaan

Vianetsintä

Pakkausmallit

Vain taidot (ei yhdistintä)

Taidot ja etäyhdistin

Vain yhdistin (ei mukautettuja taitoja)

Tuotu Claude Code- tai Cursor-laajennus

Taitojen laatimisen parhaat käytännöt

Tehokkaiden kuvausten kirjoittaminen

Luo tehokkaita työnkulkuja

Vältä yleisiä virheitä

Kelpoisuussäännöt

Kokoonpanotietotason tarkistus

Pakettitason validointi

Yhdistimen validointi

Oheistiedoston tarkistus

Käyttöympäristöjen välinen yhteensopivuus

MCP-merkintöjen ja vahvistusten hallinta

Käytettävissä olevat kentät

Vahvistussäännöt

MCP-esimerkkejä

Mitä on saatavilla nyt

Tiedostojen hyväksyminen Cowork-työtilasta

Tiedostoparametrin määritteleminen

Mitä agentti näkee

Sisäkkäiset tiedostoparametrit

Mitä palvelimesi vastaanottaa?

Rajoitukset

Suositukset

Tunnista palvelimellesi tuleva Cowork-liikenne

copilot-cowork-etuliitetäsmäytys

Oikean kanavan valinta porttiin

Mitä identiteetti sisältää ja ei sisällä

Yleisiä kysymyksiä

Liittyvät tiedot

Palaute

Lisäresursseja

Kuvaile yhdistimen työkaluja (`mcpToolDescription`)

`copilot-cowork`-etuliitetäsmäytys