/add-skill: document the trust model for imported (executable) skills

[alencheung]

Summary

/add-skill imports a skill from the Power CAT skills gallery (or a local upload) into a cloned Copilot Studio workspace:

Import writes the skill under behaviors/<name>/: the manifest as SKILL.md and every other payload file (e.g. scripts/) copied verbatim.

(commands/add-skill.md, step 5; scripts/add-skill.js importSkill() walks every file in the source folder and writes it into the workspace, archives included.)

Two things are missing around that copy:

1. No statement of what an imported skill is or can do. A skill is not inert data: SKILL.md is instruction content the assistant follows when working in that workspace, and a scripts/ payload is runnable on request. None of the command doc, the README, or reference/skill-schema.md says this. A user who imports "a skill" has no indication they just placed executable content into a workspace where an AI assistant operates.

2. No statement of the gallery's trust model. The download path is fixed — scripts/add-skill.js resolves everything from a single Microsoft-hosted GitHub repository and its pages site, never from arbitrary hosts — but the plugin never says what review a gallery entry carries (curated? community submission? version-pinned?). Without that, users cannot make an informed choice between a gallery pick and a local upload, and the security story silently depends on facts ("fixed hosts, one repo") that exist only in the code.

Suggestions (any of these; docs alone would already help)

• Add a short trust-model note to the /add-skill docs and the README: what a skill is, that SKILL.md steers the assistant and scripts/ may be executed on request, and what curation/review status the gallery carries.
• At import time, surface the executable payload: list scripts/ (and any archives) that will land in the workspace, or ask for a one-time confirmation before writing them. The importer already computes the full file list (walkFiles), so the notice is cheap.
• If gallery entries are curated/reviewed, say so explicitly in the docs; if they accept community submissions, say that instead and let the import notice carry the weight.

This is a documentation/consent gap rather than a code defect — the import itself is containment-safe (staged copy, path-sanitized folder names, no post-import execution) — but the trust decision currently happens with no information shown to the user.

Verified at HEAD a0833db3 (default branch main), 2026-09-20.