diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..32304a3 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,17 @@ +{ + "name": "Managed-Apps", + "plugins": [ + { + "name": "microsoft-managed-apps", + "source": { + "source": "local", + "path": "./plugins/microsoft-managed-apps" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6af1eac..105a81b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ "name": "microsoft-managed-apps", "source": "./plugins/microsoft-managed-apps", "description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.", - "version": "2.1.6" + "version": "2.1.7" } ] } diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml new file mode 100644 index 0000000..09b1d18 --- /dev/null +++ b/.github/workflows/pr.yml @@ -0,0 +1,41 @@ +name: PR pipeline + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + plugin-compatibility: + name: Plugin compatibility (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: actions/setup-node@v7 + with: + node-version: '22' + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + - name: Install the pinned Agent Skills reference validator + run: python -m pip install -r scripts/requirements-plugin-validation.txt + - name: Validate manifests and marketplace entries + run: node scripts/validate-plugin-compatibility.mjs + - name: Test compatibility validation + run: node --test scripts/validate-plugin-compatibility.test.mjs + - name: Validate every packaged skill + run: python scripts/validate_plugin_skills.py + - name: Test skill validation + run: python -m unittest discover -s scripts -p "*_test.py" + - name: Test attribution hooks + run: node --test scripts/plugin-hooks.test.mjs diff --git a/plugins/microsoft-managed-apps/.claude-plugin/plugin.json b/plugins/microsoft-managed-apps/.claude-plugin/plugin.json index 0fa8295..a78891d 100644 --- a/plugins/microsoft-managed-apps/.claude-plugin/plugin.json +++ b/plugins/microsoft-managed-apps/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "microsoft-managed-apps", - "version": "2.1.6", + "version": "2.1.7", "description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.", "author": { "name": "Microsoft", diff --git a/plugins/microsoft-managed-apps/AGENTS.md b/plugins/microsoft-managed-apps/AGENTS.md index 7c159f0..03bf68c 100644 --- a/plugins/microsoft-managed-apps/AGENTS.md +++ b/plugins/microsoft-managed-apps/AGENTS.md @@ -115,14 +115,17 @@ skills// --- name: kebab-case-name description: Short, action-oriented sentence the model uses for retrieval. Mention `ms` CLI verbs explicitly. -user-invocable: true -allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, ... -model: sonnet # or opus for design-heavy work +allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. ``` +Use only [Agent Skills frontmatter fields](https://agentskills.io/specification). +Keep one skill set for all clients. Do not add `model` or `user-invocable`. +Skills inherit the client's selected model. Claude's default keeps skills user-invocable. +Resolve resource links relative to the containing Markdown file, not the user's project. + ## Agent | Agent | Purpose | @@ -133,6 +136,35 @@ model: sonnet # or opus for design-heavy work After modifying this plugin: -1. Bump the `version` field in `.claude-plugin/plugin.json` and the matching plugin entry in the repo-root `.claude-plugin/marketplace.json`. -2. Test in a fresh project: `/create-app` end-to-end, then a representative `/add-*`. -3. Verify any new `allowed-tools` entries are minimal — request only what the skill needs. +1. Update the canonical `plugin.json` at this plugin's root, including its version. +2. Copy its metadata to `.claude-plugin/plugin.json`, excluding only `$schema`. Keep both files as regular JSON files, never symlinks. +3. Update the matching version and description in the repo-root `.claude-plugin/marketplace.json`. Preserve its marketplace name, plugin name, and source path. +4. Keep the repo-root `.agents/plugins/marketplace.json` entry pointed at this same plugin directory. +5. Run `node scripts/validate-plugin-compatibility.mjs` from the repository root. +6. Run `node --test scripts/validate-plugin-compatibility.test.mjs` from the repository root. +7. Install validation dependencies with `python -m pip install -r scripts/requirements-plugin-validation.txt` in a virtual environment. +8. Run `python scripts/validate_plugin_skills.py`. +9. Run `python -m unittest discover -s scripts -p "*_test.py"`. +10. Run `node --test scripts/plugin-hooks.test.mjs`. +11. Follow the client test matrix in [README.md](README.md) before claiming runtime compatibility. +12. Verify any new `allowed-tools` entries are minimal — request only what the skill needs. + +Keep `agents/microsoft-apps-architect.md` as the source for the architect. +Copy it to `com.github.copilot/agents/microsoft-apps-architect.agent.md` after each edit. +Change its `../shared/` links to `../../shared/` and `../skills/` links to `../../skills/` in the copy. +The validator rejects any other difference. + +Keep executable hooks in `hooks/`. Do not copy their scripts. +Claude and legacy Copilot discover `hooks/hooks.json`. +Agent Plugins Copilot discovers `com.github.copilot/hooks/hooks.json`. +The latter uses native Copilot events, `${PLUGIN_ROOT}`, and the same scripts. +Validation checks both configurations for equivalent scripts, matchers, and timeouts. +Keep both hook payload contracts when editing a script. + +The canonical manifest follows [Agent Plugins 1.0.0](https://agent-plugins.org/specification). +That version requires root `plugin.json`, not the older `.plugin/plugin.json` layout. +The generic `PR pipeline` workflow in `.github/workflows/pr.yml` contains one job: plugin compatibility. +This job checks manifests, component compatibility, resource links, skill validity, and hooks on Windows and Ubuntu. +The Python dependency is the Agent Skills reference validator, pinned to a Git commit. +Add future PR checks as separate jobs in this workflow. +Client installation, updates, shared-resource resolution, and hook behavior still need host-level checks before claiming support for a new client. diff --git a/plugins/microsoft-managed-apps/README.md b/plugins/microsoft-managed-apps/README.md index c3e0285..4d0e959 100644 --- a/plugins/microsoft-managed-apps/README.md +++ b/plugins/microsoft-managed-apps/README.md @@ -40,6 +40,8 @@ The `/create-app` skill handles the global install of `@microsoft/managed-apps-c ## Install the plugin +### Claude Code and GitHub Copilot + 1. Open your copilot in any project folder: ``` claude @@ -59,6 +61,169 @@ The `/create-app` skill handles the global install of `@microsoft/managed-apps-c /plugin install microsoft-managed-apps@Managed-Apps ``` +### Agent Plugins and Codex discovery + +The canonical manifest is `plugins/microsoft-managed-apps/plugin.json`, relative to the repository root. +It declares the [Agent Plugins 1.0.0 schema](https://agent-plugins.org/specification). +The published format uses root `plugin.json`, not `.plugin/plugin.json`. +Compatible clients discover the existing `skills/` directory from this plugin root. +This package does not bundle an MCP server, so it does not need `mcp.json`. + +For Codex, the repository includes `.agents/plugins/marketplace.json`, following the +[Codex packaging guide](https://developers.openai.com/plugins/build/plugins). +Its entry points to the same plugin directory as the existing Claude marketplace. + +To evaluate a local checkout containing these changes: + +1. Add its repository root with `codex plugin marketplace add `. +2. Open the Plugins Directory in the ChatGPT desktop app with Codex plugin support. +3. Select `Managed-Apps` and install `microsoft-managed-apps`, following the current Codex packaging guide. +4. Start a new session before checking the installed skills. + +**Compatibility status:** the portable package does not establish full Codex runtime support. +Skills use document-relative links to shared resources. They do not require `${CLAUDE_PLUGIN_ROOT}`. +The package does not provide a Codex architect agent or Codex hooks. +Shared instructions request `plugin/codex` attribution while preserving an existing `MS_CLI_ORIGIN` value. +This attribution depends on the agent following instructions, not hook enforcement. +Complete the client checks below before using workflows that change resources. + +### Compatibility layout and model selection + +| Path within the plugin | Consumer and purpose | +| --- | --- | +| `plugin.json` | Canonical Agent Plugins 1.0.0 metadata. | +| `.claude-plugin/plugin.json` | Claude Code and legacy clients. Regular JSON mirror, excluding only `$schema`. | +| `skills/` | One portable skill set for all clients. | +| `agents/microsoft-apps-architect.md` | Claude Code and legacy Copilot architect. | +| `com.github.copilot/agents/microsoft-apps-architect.agent.md` | Architect copy for Copilot's Agent Plugins discovery. Only relative resource paths differ. | +| `hooks/hooks.json` | Claude Code and legacy Copilot hook configuration. | +| `com.github.copilot/hooks/hooks.json` | Native Copilot hook configuration using `${PLUGIN_ROOT}`. | +| `hooks/*.sh` and `hooks/*.ps1` | Shared executable hooks. Both configurations run these same scripts. | + +Keep the Claude manifest. Claude still reads it even when a newer Copilot selects the root manifest. +Neither marketplace nor plugin identity changes. All compatibility copies are regular files, not symlinks. + +**Intentional behavior change for review:** skills now inherit the model selected in the client. +Version 2.1.4 requested Sonnet or Opus through Claude-specific `model` fields. +The portable skill set removes those overrides instead of duplicating skill definitions. +This can change response quality, speed, and cost for Claude users. +The team must review this exception to issue #34's unchanged-behavior requirement. +The removed `user-invocable: true` field matches Claude's default, so skills remain user-invocable. +The workflow instructions and tool permissions remain, with portable resource links. + +Version 2.1.6 includes `/add-backend`, bringing the current package to 22 skills. +The recorded 2.1.4-to-2.1.5 results below cover the earlier 21-skill package. + +### Package maintenance and validation + +The legacy `.claude-plugin/plugin.json` is a regular JSON mirror of the canonical manifest, excluding only `$schema`. +This preserves the legacy format while the canonical manifest declares the Agent Plugins version. +Do not replace either file with a symlink. +The existing `.claude-plugin/marketplace.json` installation path, marketplace identity, and plugin identity remain unchanged. + +From the repository root, run: + +```sh +node scripts/validate-plugin-compatibility.mjs +node --test scripts/validate-plugin-compatibility.test.mjs +python -m pip install -r scripts/requirements-plugin-validation.txt +python scripts/validate_plugin_skills.py +python -m unittest discover -s scripts -p "*_test.py" +node --test scripts/plugin-hooks.test.mjs +``` + +Run the Python commands in a virtual environment with Python 3.11 or later. +Python is a development dependency, not a new requirement for plugin installation. +The existing Bash hooks still require a working Python interpreter. + +The generic `PR pipeline` workflow in `.github/workflows/pr.yml` runs plugin compatibility as its first and only job. +This job runs these checks on Windows and Ubuntu. Add future PR checks as separate jobs in the same workflow. +To block merges, require both platform-specific `Plugin compatibility` checks in the repository ruleset. +Validation checks manifests, regular files, metadata equivalence, marketplace identity, architect copies, hook configurations, and local resource links. +The pinned Agent Skills reference library checks every immediate skill directory. +Regression tests reject invalid skill metadata, missing components, and compatibility drift. +Hook tests check both payload formats, command attribution, user overrides, and paths containing spaces. +Windows tests execute PowerShell scripts. Ubuntu tests execute Bash scripts. +Only the canonical `$schema` field is excluded from the manifest comparison. +Object key order and whitespace do not affect the comparison. +Update both manifests and the legacy marketplace version together for each release. + +### Client test matrix + +Package checks cannot prove client runtime compatibility. +Record the exact client version, OS, source revision, commands, observed components, and results for each row. +Run install and upgrade checks in disposable client profiles, never an existing customer profile. +Do not mark an unexecuted check as passed. + +| Client and scenario | Required result | Current evidence | +| --- | --- | --- | +| Claude Code, fresh install | 22 skills, architect, both hooks, resource links, daily version check, selected model, `/create-app`, and one `/add-*`. | Pending. Claude is not installed on the implementation machine. | +| Claude Code, upgrade from 2.1.4 | Same components after update, without reinstalling. Existing marketplace and plugin identities remain. | Pending. | +| Copilot CLI, fresh install on Windows | 22 skills, architect from `com.github.copilot`, both hooks, resource links, daily version check, and user attribution overrides. | Earlier local marketplace installation and discovery passed for 21 skills. Runtime agent and hook loading remain pending. | +| Copilot CLI, upgrade from 2.1.4 on Windows | Same components and identity after update, without reinstalling. | Local marketplace changed from 2.1.4 to 2.1.5 with the same 21 skill names and one `Managed-Apps` registration. Git-backed update and runtime checks remain pending. | +| Codex, fresh install | 22 skills, resolved shared resources, representative CLI attribution, and documented absence of bundled agents/hooks. | Pending. Codex is not installed on the implementation machine. | +| Windows and Linux client flows | Fresh and upgrade results agree across platforms. | Windows local discovery evidence only. Both CI platforms are configured. Linux client flows remain pending. | +| Activation and updates | Disable and enable without reinstalling. No duplicate identity. Malformed or drifted compatibility files fail CI. | Negative package checks pass locally. Activation remains pending because the installed CLI rejects the documented enable/disable subcommands. | + +The Windows checks ran on 2026-10-26. +`copilot --version` reported `1.0.102-0.unstable.r40029025960.g5a14a15`. +The local CLI dispatcher supports installation and skill listing but rejects `plugin list --json` and `plugin enable`/`disable`. +These limits prevent a full runtime-support claim. + +#### Commands and evidence + +For a fresh Copilot check, set `COPILOT_HOME` to an empty disposable directory. +Set `COPILOT_AUTO_UPDATE=false` to prevent unrelated marketplace updates. +Run these commands from a disposable project: + +```text +copilot --version +copilot plugin marketplace add +copilot plugin install microsoft-managed-apps@Managed-Apps +copilot plugin list +copilot plugin marketplace list +copilot skill list --json +``` + +Captured local results: installation reported `Installed 21 skills`. +The plugin list contained one enabled `microsoft-managed-apps@Managed-Apps (v2.1.5)` entry. +The skill list contained all 21 packaged skill names. + +For the local upgrade check, export baseline commit `a069a3a2b8702db7f2cff2499b3162d2fee3d539` with `git archive`. +Include `plugins/microsoft-managed-apps` and `.claude-plugin/marketplace.json`. +Extract the archive into a disposable marketplace directory. +Register and install that directory with the fresh-install commands above. +Capture the 2.1.4 plugin and skill lists. +Replace its plugin files and marketplace manifest with the candidate files, without changing its registered path. +Then run: + +```text +copilot plugin marketplace update Managed-Apps +copilot plugin update microsoft-managed-apps@Managed-Apps +copilot plugin list +copilot plugin marketplace list +copilot skill list --json +``` + +Captured local results: version changed from 2.1.4 to 2.1.5, all 21 skill names matched, and one marketplace registration remained. +The CLI reported that the local plugin loads live and needs no copy or reinstall. +This does not prove a Git-backed cache update. + +For Git-backed Claude and Copilot upgrades, install baseline 2.1.4 through a disposable marketplace pointing at that revision. +Advance that same source to the candidate revision. +In each client's interactive session, run `/plugin marketplace update Managed-Apps` and `/plugin update microsoft-managed-apps@Managed-Apps`. +Do not uninstall, reinstall, or add another marketplace. +Record `/plugin`, `/skills`, and `/agent` results using the commands supported by that client version. +Run the client's enable/disable actions and confirm that the same components return. + +For each supported Claude and Copilot runtime, run `ms --version` through a shell tool. +Capture the rewritten command or CLI attribution evidence. +Repeat with `MS_CLI_ORIGIN=review/custom` already set and confirm that the hook preserves it. +Check session-start guidance and the daily version-check instructions. +Run `/create-app` and a representative `/add-*` only in an authorized test environment. +For Codex, verify the documented instruction-based attribution instead of expecting a hook. +Attach client versions, commands, and sanitized results to the PR before claiming full runtime compatibility. + ## Try it ``` @@ -75,6 +240,9 @@ This plugin sets an attribution tag on the `@microsoft/managed-apps-cli` (`ms`) - **What it does not do:** it does not run for non-`ms` commands, and it does not transmit anything itself. - **Opting out:** set `MS_CLI_ORIGIN` yourself (in your shell environment or inline on the command) and the hook leaves your value untouched. You can also disable the hook by removing/editing `hooks/hooks.json`, or refer to the `ms` CLI documentation for its own telemetry controls. +For Agent Plugins Copilot, the hook configuration is `com.github.copilot/hooks/hooks.json`. +Disable hooks in the client's settings rather than editing only the legacy configuration. + ## Uninstall ``` diff --git a/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md b/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md index 2898823..5a574d5 100644 --- a/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md +++ b/plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md @@ -3,7 +3,7 @@ name: microsoft-apps-architect description: Managed apps Architect specializing in React/Vite architecture, the @microsoft/managed-apps-cli (ms) toolchain, connector and data-source patterns, and local-dev-first iteration. Use when making architecture decisions, designing data models, selecting connectors, or troubleshooting `ms app create` / `ms app dev` / build issues. --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** - Cross-cutting concerns (CLI install, env vars, planning, memory bank, execution style). +**📋 Shared Instructions: [shared-instructions.md](../shared/shared-instructions.md)** - Cross-cutting concerns (CLI install, env vars, planning, memory bank, execution style). # Managed apps Architect diff --git a/plugins/microsoft-managed-apps/com.github.copilot/agents/microsoft-apps-architect.agent.md b/plugins/microsoft-managed-apps/com.github.copilot/agents/microsoft-apps-architect.agent.md new file mode 100644 index 0000000..b0881fd --- /dev/null +++ b/plugins/microsoft-managed-apps/com.github.copilot/agents/microsoft-apps-architect.agent.md @@ -0,0 +1,162 @@ +--- +name: microsoft-apps-architect +description: Managed apps Architect specializing in React/Vite architecture, the @microsoft/managed-apps-cli (ms) toolchain, connector and data-source patterns, and local-dev-first iteration. Use when making architecture decisions, designing data models, selecting connectors, or troubleshooting `ms app create` / `ms app dev` / build issues. +--- + +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** - Cross-cutting concerns (CLI install, env vars, planning, memory bank, execution style). + +# Managed apps Architect + +You are a managed apps Architect with deep expertise in building web apps on the managed apps platform. Your toolchain is `@microsoft/managed-apps-cli` (binary `ms`). + +## Execution Guardrails + +- **Skill-first**: Before taking any action, check whether a skill exists for it. Use `/create-app`, `/dev`, `/deploy`, `/share`, and `/add-*` skills when applicable. Never do ad-hoc what a skill already handles. +- **Local-dev-first, not deploy-every-cycle**: The default inner loop is `ms app dev` (local App Player with hot reload), not deploy. Only deploy when the user explicitly asks. +- **Connector-first for external integrations**: never propose raw `fetch`/`axios` calls when a Power Platform connector exists. The App Player sandbox blocks arbitrary outbound HTTP. + +## Your Expertise + +- **React + Vite**: Component architecture, state management, TypeScript strict mode. +- **Managed apps platform**: How `ms app create` provisions app metadata + a remote git repository, how `ms app dev` runs a two-server local stack (dev + config) against the App Player, and how `ms app deploy` gets the app into the cloud. +- **Connector patterns**: Understanding all available connectors (Office 365 Outlook, Office 365 Users, Teams, SharePoint, OneDrive, Excel, Azure DevOps, Dataverse) and intelligently selecting them based on app requirements using the Connector Decision Guide. +- **Connector Decision Guide** ([shared/connector-decision-guide.md](../../shared/connector-decision-guide.md)): You must reference this guide when recommending connectors. Apply the decision trees and common app patterns to match user scenarios to the right connector(s). +- **Shared connection policies** ([shared/allowed-actions.md](../../shared/allowed-actions.md)): When a connection reference is shared (`sharedConnectionId` set in `ms.config.json`), the app must declare `allowedActions` or the deploy fails validation. Raise this while recommending a connector, not after — it shapes what the app is permitted to do at runtime. + +## Your Role + +When consulted, you provide guidance on: + +1. **Architecture Decisions**: Component structure, state management, data fetching patterns. +2. **Dataverse Integration**: Picklist, lookup, virtual field, and file/image column patterns. (See data-source skills' reference docs.) +3. **Connector Selection**: Which connector to use for a given use case. +4. **TypeScript Patterns**: Strict mode compliance, typing useState with enum values, working with generated codegen output in the `generated/` directory. +5. **Build & Deploy**: Choosing between local dev (`ms app dev`), local-built deploy (`npm run build` + `git add -A` + `git commit` + `git push` + `ms app deploy`), and cloud-built deploy (`git add -A` + `git commit` + `git push` + `ms app deploy [--commit ]`). + +## Before Starting Any Task + +Verify prerequisites — the `/create-app` skill handles this automatically, but if invoked directly: + +```bash +node --version # Must be v22+ +ms --version # Bin name has flipped between dev builds +``` + +- **Node.js below v22**: Report "Node.js 22+ is required. Upgrade or switch with `nvm use 22`." and STOP. +- **Missing `ms`**: Direct the user to `/create-app`, which installs `@microsoft/managed-apps-cli@latest` globally from the public npm registry. Never instruct them to `npm install --save-dev` per-workspace — install globally so the `ms` binary is on PATH and the workspace stays clean. +- **All present**: Report versions and proceed. + +## Key Considerations for managed apps + +### App backend database + +Rayfin provides the app backend database; it is not a connector. + +Before recommending or using Rayfin, pass the +[Rayfin feature gate](../../shared/shared-instructions.md#rayfin-feature-gate). + +When the gate passes and the user explicitly requests an app backend database +(including `/add-backend` or Rayfin), use +[/add-backend](../../skills/add-backend/SKILL.md). + +### Connector-First Principle + +**For external integrations, use Power Platform connectors rather than raw HTTP calls.** Managed apps run in the App Player sandbox, which blocks arbitrary outbound HTTP. + +**When recommending connectors, always:** +1. Start with the user's app goal (not available connectors) +2. Reference the [Connector Decision Guide](../../shared/connector-decision-guide.md) +3. Apply the appropriate decision tree (search, CRUD, AI, or hybrid) +4. Explain the trade-offs if multiple options exist + +| App needs to... | Use this connector / skill | Why | +| ---------------------------------------------------- | ------------------------------------- | --- | +| Store and manage custom business data (tables, CRUD) | Dataverse (`/add-dataverse`) | Purpose-built database | +| Track work items, bugs, or pipelines | Azure DevOps (`/add-azuredevops`) | Work item CRUD | +| Send or read Teams messages | Teams (`/add-teams`) | Direct Teams actions | +| Read or write Excel workbook data | Excel Online (`/add-excel`) | Spreadsheet operations | +| Upload, download, or manage files | OneDrive (`/add-onedrive`) | File versioning and management | +| Read lists or manage documents in SharePoint | SharePoint (`/add-sharepoint`) | Direct list/document operations | +| Send emails, read inbox, manage calendar | Office 365 Outlook (`/add-office365`) | Native calendar API with CRUD | +| Read profiles, managers, direct reports, or photos | Office 365 Users (`/add-office365-users`) | Microsoft 365 directory and org relationships | +| Search M365 knowledge-grounded content | Work IQ (`/add-workiq`) | Semantic cross-M365 search/chat | +| Invoke a Copilot Studio agent | MCS Copilot (`/add-mcscopilot`) | Agent invocation | +| Connect to any other service | Generic (`/add-data-source`) | Fallback for unlisted connectors | + +**See** [Connector Decision Guide](../../shared/connector-decision-guide.md) for decision trees, common app patterns, and scenario examples. + +### Shared Connections Need an Action Policy + +The CLI records a `sharedConnectionId` on a connection reference automatically whenever the +connector's authentication type is shareable. Such a reference **must** declare +`allowedActions` in `ms.config.json`, or `ms app pack` / `ms app deploy` fails validation. + +- **Tabular** references (those with `dataSets[*].dataSources[*]`) declare per-table actions + from a fixed vocabulary: `"get"`, `"post"`, `"patch"`, `"delete"`. Every table needs one. +- **Action** connectors declare connector-level Action IDs from + `ms connector list-actions --connector --json`. + +Architecturally this is a least-privilege boundary, not a formality: RP translates the +declaration into an `executionRestrictions` runtime policy, and APIHub runs every connector +request through that policy — anything not declared is refused. When you design a data model +against a shared connection, design the action set with it — a reference that reads one table +and writes another should say so. + +It is authoring-only. It is never read at runtime and requires no app code, no SDK upgrade, and +no client-side check. + +**See** [allowed-actions.md](../../shared/allowed-actions.md). + +### Generated Code Pattern + +`ms app add data-source` (with `--as table` or `--as action`) writes generated TypeScript to the `generated/` directory at the project root. The exact subdirectory layout is owned by `@microsoft/apps-actions`; expect `generated/services/*Service.ts` and `generated/models/*Model.ts` files. Import them from your `src/` code using relative paths like `../../generated/services/`. Always use these generated services for data access. + +Binary connector responses require runtime narrowing: `image/*` and +`application/octet-stream` responses arrive as `Uint8Array` even when generated TypeScript +declares `string`. For profile photos, follow `/add-office365-users` and convert the bytes to a +base64 `data:` URL rather than a CSP-sensitive `blob:` URL. + +### Scaffolding + +`ms app create` writes the project from a built-in Vite template, initializes a git repo, and wires it to a remote. Do NOT scaffold the project manually (`git clone`, `npm create vite@latest`, file-by-file creation) — `ms app create` is the only supported path. + +```bash +ms app create --display-name "" --non-interactive +``` + +### Environment Selection + +By default, run `ms app create` with no environment flags and let the CLI resolve the environment automatically — keep the environment concept hidden from end users. Pass `--environment-id ` **only** when the user explicitly provides an environment ID; never discover or construct one. If environment routing fails, surface the actual error rather than attempting an environment workaround. + +### Build & Deploy Modes + +Three paths; pick based on intent: + +| Goal | Commands | +| ------------------------------------------ | ------------------------------------------------- | +| Iterate locally (default loop) | `ms app dev` — hot reload against the App Player | +| Ship with a local-built artifact | `npm run build`, `git add -A`, `git commit`, `git push`, then `ms app deploy` | +| Ship with a server-built artifact (commit) | `git add -A`, `git commit`, `git push`, then `ms app deploy --commit ` | + +`ms app build` exists and is marked deprecated in the CLI source; `ms app deploy` covers the cloud-built path on its own. + +### Binary Name + +Use the `ms` binary: + +```bash +ms --version +``` + +Template downstream commands with `ms`. + +### First-Run Git Credential Manager Trap + +The first `ms app create` against a fresh account can fail while fetching the native Git remote because Git Credential Manager hasn't done the interactive browser flow. Symptom: `Could not commit and push the initial scaffold` with `Authentication failed for 'https://.d.environment.api.powerplatform.com/...'`. The app and scaffold were created: do **not** delete the app or rerun create. Recover in the project directory with `git fetch origin` (browser pops, approve). + +## Response Style + +- Be direct and practical. +- Provide code examples when helpful. +- Always consider sandbox constraints (no raw HTTP, connector-proxied calls only). +- Suggest the simplest solution that meets requirements. \ No newline at end of file diff --git a/plugins/microsoft-managed-apps/com.github.copilot/hooks/hooks.json b/plugins/microsoft-managed-apps/com.github.copilot/hooks/hooks.json new file mode 100644 index 0000000..f0eaba2 --- /dev/null +++ b/plugins/microsoft-managed-apps/com.github.copilot/hooks/hooks.json @@ -0,0 +1,24 @@ +{ + "version": 1, + "hooks": { + "sessionStart": [ + { + "type": "command", + "bash": "bash \"${PLUGIN_ROOT}/hooks/session-start.sh\"", + "powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}/hooks/session-start.ps1\"", + "env": { "COPILOT_CLI": "1" }, + "timeoutSec": 5 + } + ], + "preToolUse": [ + { + "type": "command", + "matcher": "Bash|bash|shell|sh|execute|execute_command|run_in_terminal|terminal|powershell|PowerShell|pwsh", + "bash": "bash \"${PLUGIN_ROOT}/hooks/pre-tool-use.sh\"", + "powershell": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}/hooks/pre-tool-use.ps1\"", + "env": { "COPILOT_CLI": "1" }, + "timeoutSec": 5 + } + ] + } +} diff --git a/plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1 b/plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1 index 35c61df..2be0f09 100644 --- a/plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1 +++ b/plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1 @@ -7,7 +7,8 @@ # Behavior: # - If the command does not invoke `ms`, allow unchanged. # - If the command already sets MS_CLI_ORIGIN inline, allow unchanged. -# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput. The +# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput +# (Claude) and modifiedArgs (Copilot). The # rewrite defaults MS_CLI_ORIGIN only when it is truly unset # (`${MS_CLI_ORIGIN-...}` for bash tools, `Test-Path Env:MS_CLI_ORIGIN` # for PowerShell tools), so ANY pre-existing value in the parent @@ -53,6 +54,7 @@ function Write-AllowWithRewrite { permissionDecision = 'allow' permissionDecisionReason = 'Auto-set MS_CLI_ORIGIN for @microsoft/managed-apps-cli attribution' updatedInput = $updated + modifiedArgs = $updated hookSpecificOutput = @{ hookEventName = 'PreToolUse' permissionDecision = 'allow' @@ -82,7 +84,7 @@ try { # Locate tool input $toolInput = $null - foreach ($prop in @('tool_input', 'input', 'toolInput')) { + foreach ($prop in @('tool_input', 'input', 'toolInput', 'toolArgs')) { if ($data.PSObject.Properties[$prop]) { $toolInput = $data.$prop; break } } if (-not $toolInput) { Write-AllowUnchanged } @@ -118,16 +120,11 @@ try { $inlinePattern = '(^|[;&|()\n\r])\s*([A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(export\s+MS_CLI_ORIGIN=|set\s+MS_CLI_ORIGIN=|MS_CLI_ORIGIN=|\$env:MS_CLI_ORIGIN\s*=)' if ($command -match $inlinePattern) { Write-AllowUnchanged } - # Detect if the command will run in PowerShell context. - # Primary: check if this hook script itself is running in PowerShell (most reliable). - # Fallback: check explicit tool_name field. - $isPowerShellTool = $false - if ($PSVersionTable) { - # Hook script is running in PowerShell; assume PowerShell commands - $isPowerShellTool = $true - } elseif ($toolName) { - $tn = $toolName.ToLowerInvariant() - if ($tn -eq 'powershell' -or $tn -eq 'pwsh') { $isPowerShellTool = $true } + # Native Copilot payloads identify the actual shell. Legacy payloads + # retain the existing platform-based fallback. + $isPowerShellTool = $true + if ($data.PSObject.Properties['toolName']) { + $isPowerShellTool = $toolName.ToLowerInvariant() -in @('powershell', 'pwsh') } if ($isPowerShellTool) { diff --git a/plugins/microsoft-managed-apps/hooks/pre-tool-use.sh b/plugins/microsoft-managed-apps/hooks/pre-tool-use.sh index a1e5b77..13f5d79 100644 --- a/plugins/microsoft-managed-apps/hooks/pre-tool-use.sh +++ b/plugins/microsoft-managed-apps/hooks/pre-tool-use.sh @@ -9,7 +9,8 @@ # - If the command does not invoke `ms`, allow unchanged. # - If the command already sets MS_CLI_ORIGIN= inline (env-prefix, `set`, # or `$env:`), allow unchanged. -# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput. The +# - Otherwise, rewrite the command via hookSpecificOutput.updatedInput +# (Claude) and modifiedArgs (Copilot). The # rewrite defaults MS_CLI_ORIGIN only when it is truly unset # (`${MS_CLI_ORIGIN-...}` for bash, `Test-Path Env:MS_CLI_ORIGIN` for # PowerShell), so ANY pre-existing value in the parent environment wins at @@ -84,7 +85,7 @@ tool_name = data.get("tool_name") or data.get("toolName") or "" if not isinstance(tool_name, str): tool_name = "" -tool_input = data.get("tool_input") or data.get("input") or data.get("toolInput") or {} +tool_input = data.get("tool_input") or data.get("input") or data.get("toolInput") or data.get("toolArgs") or {} if not isinstance(tool_input, dict): emit_allow() @@ -148,12 +149,12 @@ else: updated = dict(tool_input) updated["command"] = new_command reason = "Auto-set MS_CLI_ORIGIN for @microsoft/managed-apps-cli attribution" -# Emit both the flat fields (Copilot CLI) and the hookSpecificOutput wrapper -# (Claude Code) so the rewrite applies regardless of host engine. +# Keep legacy fields, native Copilot modifiedArgs, and the Claude wrapper. print(json.dumps({ "permissionDecision": "allow", "permissionDecisionReason": reason, "updatedInput": updated, + "modifiedArgs": updated, "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", diff --git a/plugins/microsoft-managed-apps/plugin.json b/plugins/microsoft-managed-apps/plugin.json new file mode 100644 index 0000000..0053bb7 --- /dev/null +++ b/plugins/microsoft-managed-apps/plugin.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "microsoft-managed-apps", + "version": "2.1.7", + "description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.", + "author": { + "name": "Microsoft", + "url": "https://github.com/microsoft/Managed-Apps" + }, + "homepage": "https://www.npmjs.com/package/@microsoft/managed-apps-cli", + "repository": "https://github.com/microsoft/Managed-Apps", + "license": "MIT", + "keywords": [ + "microsoft-managed-apps", + "managed-apps-cli", + "dataverse", + "react", + "vite" + ] +} diff --git a/plugins/microsoft-managed-apps/shared/shared-instructions.md b/plugins/microsoft-managed-apps/shared/shared-instructions.md index a4e6318..e87de35 100644 --- a/plugins/microsoft-managed-apps/shared/shared-instructions.md +++ b/plugins/microsoft-managed-apps/shared/shared-instructions.md @@ -4,6 +4,27 @@ All skills reference this single file. When new shared instructions are added, update this file only — no changes needed to individual skills. +Resolve packaged resource links relative to the file that contains the link, not the user's project directory. +The plugin does not select an AI model. Use the model selected in the client. + +## CLI attribution without hooks + +Claude Code and Copilot use the packaged hooks to set CLI attribution. +Do not add another attribution prefix when those hooks are active. + +The package does not provide Codex hooks. In Codex, default `MS_CLI_ORIGIN` to `plugin/codex` before an `ms` command. +Preserve any existing value, including an empty value. Use the syntax for the active shell: + +```bash +export MS_CLI_ORIGIN="${MS_CLI_ORIGIN-plugin/codex}" +``` + +```powershell +if (-not (Test-Path Env:MS_CLI_ORIGIN)) { $env:MS_CLI_ORIGIN = 'plugin/codex' } +``` + +This Codex behavior depends on the agent following these instructions. No hook enforces it. + --- ## Safety Guardrails diff --git a/plugins/microsoft-managed-apps/shared/version-check.md b/plugins/microsoft-managed-apps/shared/version-check.md index 431112f..85ebd33 100644 --- a/plugins/microsoft-managed-apps/shared/version-check.md +++ b/plugins/microsoft-managed-apps/shared/version-check.md @@ -13,7 +13,8 @@ Look for the file `~/.microsoft-managed-apps-last-version-check`. Read it if it ### Step 2: Read the local version -Read `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json` and extract the `version` field. +Read [the canonical plugin manifest](../plugin.json) and extract the `version` field. +Resolve this path relative to this instruction file, not the user's project. ### Step 3: Fetch the latest version from the marketplace diff --git a/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md b/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md index 78eaf8b..a08c504 100644 --- a/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-azuredevops/SKILL.md @@ -1,12 +1,10 @@ --- name: add-azuredevops description: Adds Azure DevOps by delegating to `/add-data-source` with `api-id=shared_visualstudioteamservices` and action mode. Use when adding Azure DevOps integration. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Azure DevOps (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-backend/SKILL.md b/plugins/microsoft-managed-apps/skills/add-backend/SKILL.md index 84e750b..452c7ff 100644 --- a/plugins/microsoft-managed-apps/skills/add-backend/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-backend/SKILL.md @@ -1,10 +1,9 @@ --- name: add-backend description: Add an app backend with `ms app add backend --provider rayfin`. Currently covers database entities and client integration. Use only when the user explicitly requests a database, /add-backend, or Rayfin, and the CLI reports the rayfin feature as enabled. -user-invocable: true --- -**Shared instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** +**Shared instructions: [shared-instructions.md](../../shared/shared-instructions.md)** # Add an app backend diff --git a/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md b/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md index 0d5d987..343f05a 100644 --- a/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md @@ -1,16 +1,14 @@ --- name: add-data-source description: Canonical add flow for Microsoft Managed Apps. Use when adding any data source through `ms app add data-source` (with `--as table` or `--as action`), or when the user wants help discovering which connector / api-id to use. -user-invocable: true -allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. -**Reference:** [connector-reference.md](${CLAUDE_PLUGIN_ROOT}/shared/connector-reference.md) — Inline connection creation, Grep-first for large generated files. +**Reference:** [connector-reference.md](../../shared/connector-reference.md) — Inline connection creation, Grep-first for large generated files. -**Reference:** [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md) — Shared connections must declare `allowedActions` before deploy (Step 4). +**Reference:** [allowed-actions.md](../../shared/allowed-actions.md) — Shared connections must declare `allowedActions` before deploy (Step 4). # Add Data Source (Canonical) @@ -166,7 +164,7 @@ For runtime-selected organizations and tables, use the action command without `- In interactive action mode, decline the optional prompt to bind a specific Dataverse table. The CLI resolves connections inline. Pass `--connection-id ` or `-c ` when a specific connection is required. -See [connector-reference.md](${CLAUDE_PLUGIN_ROOT}/shared/connector-reference.md) for connection selection. +See [connector-reference.md](../../shared/connector-reference.md) for connection selection. After a Dataverse add, check the new reference in `ms.config.json`. Its `id` must be `/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps`, unless the user explicitly requested the older connector. @@ -246,7 +244,7 @@ can reach a failing deploy — not silently forgotten. **4d. Write the confirmed values into `ms.config.json`** (skip when deferring). -Full rules, worked examples, and failure recovery: [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md). +Full rules, worked examples, and failure recovery: [allowed-actions.md](../../shared/allowed-actions.md). ### Step 5: Build diff --git a/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md b/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md index 34b1e30..5aa2e82 100644 --- a/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-dataverse/SKILL.md @@ -1,12 +1,10 @@ --- name: add-dataverse description: Adds Microsoft Dataverse through `/add-data-source` with `api-id=shared_commondataserviceforapps`. Use for existing table bindings or Dataverse actions. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: opus +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Dataverse (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md b/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md index 7fe909a..b75c107 100644 --- a/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-excel/SKILL.md @@ -1,12 +1,10 @@ --- name: add-excel description: Adds Excel Online (Business) by delegating to `/add-data-source` with `api-id=shared_excelonlinebusiness` and table mode. Use when binding Excel tables. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Excel Online (Business) (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md b/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md index 050af74..e0c2a28 100644 --- a/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-mcscopilot/SKILL.md @@ -1,12 +1,10 @@ --- name: add-mcscopilot description: Adds Microsoft Copilot Studio by delegating to `/add-data-source` with `api-id=microsoftcopilotstudio` and action mode. Use when integrating Copilot Studio agents. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Microsoft Copilot Studio (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-office365-users/SKILL.md b/plugins/microsoft-managed-apps/skills/add-office365-users/SKILL.md index b854e78..ec26487 100644 --- a/plugins/microsoft-managed-apps/skills/add-office365-users/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-office365-users/SKILL.md @@ -1,12 +1,10 @@ --- name: add-office365-users description: Adds Office 365 Users by delegating to `/add-data-source` with `api-id=shared_office365users` and action mode. Use for user profiles, managers, direct reports, people search, and profile photos. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Office 365 Users (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md b/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md index bafc336..4e9d7b9 100644 --- a/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-office365/SKILL.md @@ -1,12 +1,10 @@ --- name: add-office365 description: Adds Office 365 Outlook by delegating to `/add-data-source` with `api-id=shared_office365` and action mode. Use when integrating Outlook mail/calendar. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Office 365 Outlook (Wrapper) @@ -160,7 +158,7 @@ const result = await Office365OutlookService.SendEmailV2({ ## Key Patterns -**📋 Generic connector response handling:** [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md#connector-response-handling) — Error handling, array access (`.data.value`), empty results, and response structure patterns apply to all connectors, including Office 365. +**📋 Generic connector response handling:** [shared-instructions.md](../../shared/shared-instructions.md#connector-response-handling) — Error handling, array access (`.data.value`), empty results, and response structure patterns apply to all connectors, including Office 365. **1. Always discover calendar ID first using `CalendarGetTables()`** diff --git a/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md b/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md index e40d320..53ed513 100644 --- a/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-onedrive/SKILL.md @@ -1,12 +1,10 @@ --- name: add-onedrive description: Adds OneDrive for Business by delegating to `/add-data-source` with `api-id=shared_onedriveforbusiness` and action mode. Use when integrating OneDrive files. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add OneDrive for Business (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md b/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md index 4938f1c..a0c578c 100644 --- a/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-sharepoint/SKILL.md @@ -1,12 +1,10 @@ --- name: add-sharepoint description: Adds SharePoint Online by delegating to `/add-data-source` with `api-id=shared_sharepointonline` and table mode. Use when binding SharePoint lists/libraries. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: opus +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add SharePoint Online (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md b/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md index 6d922b1..4f4c7ec 100644 --- a/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md +++ b/plugins/microsoft-managed-apps/skills/add-sharepoint/references/sharepoint-reference.md @@ -169,4 +169,4 @@ await SharePointOnlineService.DeleteItem({ }); ``` -Use `Grep` to find specific methods in `generated/services/SharePointOnlineService.ts` (generated files can be very large — see [connector-reference.md](${CLAUDE_PLUGIN_ROOT}/shared/connector-reference.md#inspecting-large-generated-files)). +Use `Grep` to find specific methods in `generated/services/SharePointOnlineService.ts` (generated files can be very large — see [connector-reference.md](../../../shared/connector-reference.md#inspecting-large-generated-files)). diff --git a/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md b/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md index cc837ab..72de492 100644 --- a/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-teams/SKILL.md @@ -1,12 +1,10 @@ --- name: add-teams description: Adds Microsoft Teams by delegating to `/add-data-source` with `api-id=shared_teams` and action mode. Use when integrating Teams messaging. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Teams (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/add-workiq/SKILL.md b/plugins/microsoft-managed-apps/skills/add-workiq/SKILL.md index bfb5d02..b3147d0 100644 --- a/plugins/microsoft-managed-apps/skills/add-workiq/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/add-workiq/SKILL.md @@ -1,12 +1,10 @@ --- name: add-workiq description: Adds Work IQ Copilot MCP by delegating to /add-data-source with api-id=shared_a365copilotchatmcp and action mode. Use when users need Microsoft 365 knowledge-grounded Work IQ search/chat. -user-invocable: true -allowed-tools: Read, AskUserQuestion, Skill -model: sonnet +allowed-tools: Read AskUserQuestion Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Add Work IQ Copilot MCP (Wrapper) diff --git a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md index d50fcf8..d71a2d4 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md @@ -1,12 +1,10 @@ --- name: create-app description: Creates managed apps using React and Vite. Use when scaffolding a new app with `ms app create` and ending on local dev with `ms app dev`. -user-invocable: true -allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, EnterPlanMode, ExitPlanMode, Skill -model: opus +allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion EnterPlanMode ExitPlanMode Skill --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. **References:** @@ -27,13 +25,13 @@ This skill scaffolds a new Microsoft App end-to-end using `@microsoft/managed-ap ### Step 1: Check Memory Bank -Check for `memory-bank.md` per [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md). If found, infer whether to resume or create a new app from the request: resume when it refers to the existing app or incomplete work; create a new sibling project when it clearly describes a different app. State the choice and continue. Ask only when the request genuinely fits both paths and choosing incorrectly could overwrite or modify existing work. +Check for `memory-bank.md` per [shared-instructions.md](../../shared/shared-instructions.md). If found, infer whether to resume or create a new app from the request: resume when it refers to the existing app or incomplete work; create a new sibling project when it clearly describes a different app. State the choice and continue. Ask only when the request genuinely fits both paths and choosing incorrectly could overwrite or modify existing work. ### Step 2: Validate Prerequisites Run prerequisite checks **first** — no point gathering requirements if the environment isn't ready. Full details in [prerequisites-reference.md](./references/prerequisites-reference.md). -The commands below are shown in bash syntax. If you are running PowerShell on Windows, use the equivalents described in [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md#shell-compatibility) and the PowerShell example in [prerequisites-reference.md](./references/prerequisites-reference.md) instead of copying the bash snippets literally. +The commands below are shown in bash syntax. If you are running PowerShell on Windows, use the equivalents described in [shared-instructions.md](../../shared/shared-instructions.md#shell-compatibility) and the PowerShell example in [prerequisites-reference.md](./references/prerequisites-reference.md) instead of copying the bash snippets literally. ```bash node --version # Must be v22+ @@ -66,7 +64,7 @@ Record the resolved bin name as `$BIN`. #### `@latest` refresh check -If `ms` was already installed, run the CLI freshness gate in [development-standards.md](${CLAUDE_PLUGIN_ROOT}/shared/development-standards.md#cli-freshness-gate) now. When npm `@latest` is newer, pause app creation and ask whether to update before proceeding. Never auto-update. +If `ms` was already installed, run the CLI freshness gate in [development-standards.md](../../shared/development-standards.md#cli-freshness-gate) now. When npm `@latest` is newer, pause app creation and ask whether to update before proceeding. Never auto-update. ### Step 3: Infer App Spec @@ -144,7 +142,7 @@ After the command succeeds, enter the target directory unless it is `.`, then se PROJECT_ROOT="$(pwd)" ``` -Now that `PROJECT_ROOT` exists, write the approved plan to `$PROJECT_ROOT/app_generated_plan.md` per [planning-policy.md](${CLAUDE_PLUGIN_ROOT}/shared/planning-policy.md) — before any implementation, so it is committed with the rest of the generated app. +Now that `PROJECT_ROOT` exists, write the approved plan to `$PROJECT_ROOT/app_generated_plan.md` per [planning-policy.md](../../shared/planning-policy.md) — before any implementation, so it is committed with the rest of the generated app. Capture from the output: the app GUID, the environment ID/name resolved by the CLI, and the remote git URL. (The environment ID appears in the App Player URL and is needed for that link — it's an internal detail, not something to surface to the user.) @@ -197,7 +195,7 @@ Run them sequentially. After each one: - `/add-workiq` → See "Work IQ Integration: MCP Session Pattern" for session management and response parsing - Other connector skills have similar guidance - Capture the service/client path and connection ID where applicable so Step 9 can import them. -- **If the sub-skill reports a shared connection** (`sharedConnectionId` in `ms.config.json`), it will defer the `allowedActions` policy rather than prompting — there's no app code to infer from yet. Record it as *shared, policy pending*. After implementation, resolve it before any pack or deploy. This does not block `ms app dev`; carry any pending policy into Step 11's summary. See [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md). +- **If the sub-skill reports a shared connection** (`sharedConnectionId` in `ms.config.json`), it will defer the `allowedActions` policy rather than prompting — there's no app code to infer from yet. Record it as *shared, policy pending*. After implementation, resolve it before any pack or deploy. This does not block `ms app dev`; carry any pending policy into Step 11's summary. See [allowed-actions.md](../../shared/allowed-actions.md). **Forward all captured context to each sub-skill so its own prompts are suppressed.** The `/state` skill needs the approved collections/properties and the CLI freshness gate outcome. The per-service skills (`/add-dataverse`, `/add-sharepoint`, etc.) and `/add-connector` each have their own prompt sequences (pick connection, pick table/list/site, choose api-id, CLI freshness, etc.). The approved plan and discovery results should contain those answers, so pass them through as `$ARGUMENTS` (or whatever invocation surface is available) when dispatching: state collections/properties, api-id, connection ID or name, table/list/site identifiers, environment URL, project root, and the CLI freshness gate outcome plus known versions. A sub-skill receiving the CLI freshness outcome must not check or prompt again. If a sub-skill still needs a required input that cannot be discovered or safely inferred, ask the user one focused question and record the answer as an amendment to the approved plan rather than letting multiple sub-skills ask interactively. @@ -263,13 +261,13 @@ Provide: 2. When you're happy with how it looks and behaves, say so. I'll commit + push your changes, run `ms app play --mode preview` to give you a cloud preview URL hosted in your environment, and *then* ask if you want me to `/deploy` to the live URL. - **Important**: the app has not been published; the frontend is running locally. If using an existing app backend database, identify it and report any blocked runtime checks. -When the user signals readiness, follow the **Ready-to-Ship Gate** in [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md) — commit, push, `ms app play --mode preview`, hand off the preview URL, then ask about `/deploy`. Do not skip the preview gate. +When the user signals readiness, follow the **Ready-to-Ship Gate** in [shared-instructions.md](../../shared/shared-instructions.md) — commit, push, `ms app play --mode preview`, hand off the preview URL, then ask about `/deploy`. Do not skip the preview gate. Do **not** list `/add-*` skills as next steps here; data sources were already wired in Step 8. (If the user later wants an additional connector, they can ask and you'll invoke the right `/add-*` mid-iteration.) ### Step 12: Update Memory Bank -Write `memory-bank.md` at `$PROJECT_ROOT/memory-bank.md` per [memory-bank.md](${CLAUDE_PLUGIN_ROOT}/shared/memory-bank.md) template. Record the environment ID the CLI resolved for reference (e.g. to reconstruct the App Player URL) — do not use it to re-target a future `ms app create`, and do not surface it to the user. +Write `memory-bank.md` at `$PROJECT_ROOT/memory-bank.md` per [memory-bank.md](../../shared/memory-bank.md) template. Record the environment ID the CLI resolved for reference (e.g. to reconstruct the App Player URL) — do not use it to re-target a future `ms app create`, and do not surface it to the user. --- diff --git a/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md b/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md index 5851852..e176871 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md +++ b/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md @@ -18,7 +18,7 @@ The CLI is published on the public npm registry: [`@microsoft/managed-apps-cli`](https://www.npmjs.com/package/@microsoft/managed-apps-cli). -**Shell note:** the snippets below are shown in bash. If you're on PowerShell, use the equivalents called out in [shared-instructions.md](../../shared/shared-instructions.md#shell-compatibility) instead of copying the bash syntax literally. +**Shell note:** the snippets below are shown in bash. If you're on PowerShell, use the equivalents called out in [shared-instructions.md](../../../shared/shared-instructions.md#shell-compatibility) instead of copying the bash syntax literally. ### Global install (pinned to `@latest`) diff --git a/plugins/microsoft-managed-apps/skills/delete-app/SKILL.md b/plugins/microsoft-managed-apps/skills/delete-app/SKILL.md index 6164c5e..36d00fa 100644 --- a/plugins/microsoft-managed-apps/skills/delete-app/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/delete-app/SKILL.md @@ -1,12 +1,10 @@ --- name: delete-app description: Deletes a Microsoft App via `ms app delete`. Use when the user asks to delete an app; always require explicit confirmation. -user-invocable: true -allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. **Two confirmations required; never auto-`--force`.** +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. **Two confirmations required; never auto-`--force`.** # Delete App diff --git a/plugins/microsoft-managed-apps/skills/deploy/SKILL.md b/plugins/microsoft-managed-apps/skills/deploy/SKILL.md index 8147595..d03cb72 100644 --- a/plugins/microsoft-managed-apps/skills/deploy/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/deploy/SKILL.md @@ -1,12 +1,10 @@ --- name: deploy description: Ships a Microsoft App to the cloud. Use when the user asks to deploy via `ms app deploy` (with optional build-status traceability flow). -user-invocable: true -allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. **Always confirm before deploy.** +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. **Always confirm before deploy.** # Deploy @@ -87,7 +85,7 @@ Any `MISSING` or `INVALID` line means the deploy will fail. **Stop and fix it** Infer the least-privilege set from what `src/` actually calls, propose it, and confirm with the user before writing. Do **not** grant everything to get past the gate, and do **not** delete -`sharedConnectionId`. See [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md). +`sharedConnectionId`. See [allowed-actions.md](../../shared/allowed-actions.md). `OK` means every shared reference is covered — continue. @@ -97,7 +95,7 @@ user before writing. Do **not** grant everything to get past the gate, and do ** npm run build ``` -Failure handling per [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md): +Failure handling per [shared-instructions.md](../../shared/shared-instructions.md): - TS6133 (unused import): remove and retry once. - Other TS errors: report file:line, STOP. @@ -174,7 +172,7 @@ If `memory-bank.md` exists: - Record the deploy path used (standard / traced). - Capture the commit SHA at deploy time. -If no memory bank exists, create one per [memory-bank.md](${CLAUDE_PLUGIN_ROOT}/shared/memory-bank.md) so subsequent skills have context. +If no memory bank exists, create one per [memory-bank.md](../../shared/memory-bank.md) so subsequent skills have context. --- @@ -183,7 +181,7 @@ If no memory bank exists, create one per [memory-bank.md](${CLAUDE_PLUGIN_ROOT}/ | Error | Fix | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `ms app deploy`: 401 / token expired | `$BIN auth login` and retry. | -| `ms app deploy`: `Invalid ms.config.json for shared connection policy enforcement` | A shared connection reference is missing `allowedActions`. The listed issues name the reference (and dataset/table) at fault. Declare them per [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md) and retry. Never remove `sharedConnectionId` to bypass this. | +| `ms app deploy`: `Invalid ms.config.json for shared connection policy enforcement` | A shared connection reference is missing `allowedActions`. The listed issues name the reference (and dataset/table) at fault. Declare them per [allowed-actions.md](../../shared/allowed-actions.md) and retry. Never remove `sharedConnectionId` to bypass this. | | `ms app deploy`: env mismatch | Active CLI env doesn't match `ms.config.json`. Either re-create/redeploy against the matching environment, or update `ms.config.json`. | | `git push`: no upstream configured | Run `git push -u origin HEAD`, then retry deploy. | | `git commit`: author identity unknown | Configure Git identity (`git config --global user.name` / `git config --global user.email`) and retry commit. | diff --git a/plugins/microsoft-managed-apps/skills/dev/SKILL.md b/plugins/microsoft-managed-apps/skills/dev/SKILL.md index bc54b28..477df95 100644 --- a/plugins/microsoft-managed-apps/skills/dev/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/dev/SKILL.md @@ -1,12 +1,10 @@ --- name: dev description: Runs a Microsoft App locally with hot reload via `ms app dev`. Use when starting or restarting local development and surfacing the App Player URL. -user-invocable: true -allowed-tools: Read, Grep, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Local Dev @@ -82,7 +80,7 @@ Then add a one-liner reminder of the iterate → preview → deploy loop: > "The browser tab hot-reloads as I edit code — tell me what to change. When you're happy with it, I'll commit + push your changes, run `ms app play --mode preview` for a cloud preview URL in your environment, and then ask if you want me to `/deploy`." -When the user signals readiness, follow the **Ready-to-Ship Gate** in [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md) — commit, push, preview, then ask about `/deploy`. +When the user signals readiness, follow the **Ready-to-Ship Gate** in [shared-instructions.md](../../shared/shared-instructions.md) — commit, push, preview, then ask about `/deploy`. If the dev server prints an error during startup (port conflict, missing `ms.config.json`, expired auth), stop the background task, surface the error verbatim, and propose the targeted fix: diff --git a/plugins/microsoft-managed-apps/skills/list-apps/SKILL.md b/plugins/microsoft-managed-apps/skills/list-apps/SKILL.md index 7677001..bfeaec9 100644 --- a/plugins/microsoft-managed-apps/skills/list-apps/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/list-apps/SKILL.md @@ -1,12 +1,10 @@ --- name: list-apps description: Discovers managed apps in the active environment via `ms app list --json` and optional `ms app show --json`. Use when listing or locating apps. -user-invocable: true -allowed-tools: Read, Grep, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # List Apps diff --git a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md index bf57d07..4e0c528 100644 --- a/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md @@ -1,12 +1,10 @@ --- name: list-connectors description: Lists connectors available in the active environment — including whether each is allowed or blocked by your organization's policy — plus the connection-bound data sources already wired into a Microsoft App. Use when discovering connectors and their operations before adding data sources. -user-invocable: true -allowed-tools: Read, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # List Connectors @@ -115,7 +113,7 @@ $BIN connector list-actions --connector --json | jq -r '.[] | select(.b > This applies to **action** connectors only. Tabular data sources take a fixed vocabulary of > `"get"` / `"post"` / `"patch"` / `"delete"` per table — never operation IDs from this -> command. See [allowed-actions.md](${CLAUDE_PLUGIN_ROOT}/shared/allowed-actions.md). +> command. See [allowed-actions.md](../../shared/allowed-actions.md). --- diff --git a/plugins/microsoft-managed-apps/skills/play/SKILL.md b/plugins/microsoft-managed-apps/skills/play/SKILL.md index ebcf6e5..8c91886 100644 --- a/plugins/microsoft-managed-apps/skills/play/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/play/SKILL.md @@ -1,12 +1,10 @@ --- name: play description: Opens a Microsoft App in the browser via `ms app play`. Use when opening the live deployed version or a cloud-hosted preview (main branch or specific commit SHA) without starting a local dev server. -user-invocable: true -allowed-tools: Read, Grep, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Play @@ -28,7 +26,7 @@ Opens a Microsoft App in the browser by fetching its cloud play URL and launchin ### Step 1: Check Memory Bank -Read `memory-bank.md` per [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md) for the app's environment/app identifiers, if recorded. +Read `memory-bank.md` per [shared-instructions.md](../../shared/shared-instructions.md) for the app's environment/app identifiers, if recorded. ### Step 2: Verify Project + Env diff --git a/plugins/microsoft-managed-apps/skills/share-link/SKILL.md b/plugins/microsoft-managed-apps/skills/share-link/SKILL.md index dbd2f97..21b8cec 100644 --- a/plugins/microsoft-managed-apps/skills/share-link/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/share-link/SKILL.md @@ -1,12 +1,10 @@ --- name: share-link description: Manages tenant-wide share links for a Microsoft App via `ms app share link create`, `ms app share link list`, and `ms app share link revoke`. Use when you want to distribute app access via a URL instead of named principals. -user-invocable: true -allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Share Link @@ -30,7 +28,7 @@ Three sub-commands: ### Step 1: Check Memory Bank -Read `memory-bank.md` per [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md) for the app's environment/app identifiers, if recorded. +Read `memory-bank.md` per [shared-instructions.md](../../shared/shared-instructions.md) for the app's environment/app identifiers, if recorded. ### Step 2: Verify Project + Env diff --git a/plugins/microsoft-managed-apps/skills/share/SKILL.md b/plugins/microsoft-managed-apps/skills/share/SKILL.md index 6074e5b..4ee8ed6 100644 --- a/plugins/microsoft-managed-apps/skills/share/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/share/SKILL.md @@ -1,12 +1,10 @@ --- name: share description: Shares (or unshares) a Microsoft App with users via `ms app share` / `ms app unshare`. Use when updating app access control. -user-invocable: true -allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. **Always confirm before share/unshare.** +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. **Always confirm before share/unshare.** # Share / Unshare diff --git a/plugins/microsoft-managed-apps/skills/state/SKILL.md b/plugins/microsoft-managed-apps/skills/state/SKILL.md index 7ce9f0d..e136579 100644 --- a/plugins/microsoft-managed-apps/skills/state/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/state/SKILL.md @@ -1,12 +1,10 @@ --- name: state description: Store and query a Microsoft Managed App's built-in state and file attachments with `ms project state` CLI schema commands and generated TypeScript clients. First, with the user signed in to the CLI, run `ms feature status --name state --json`; if `feature.enabled` is not `true`, recommend an alternative connector or data source. -user-invocable: true -allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion -model: sonnet +allowed-tools: Read Edit Write Grep Glob Bash AskUserQuestion --- -**📋 Shared Instructions: [shared-instructions.md](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)** — Cross-cutting concerns. +**📋 Shared Instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — Cross-cutting concerns. # Managed Apps State with CLI schema + generated client diff --git a/scripts/plugin-hooks.test.mjs b/scripts/plugin-hooks.test.mjs new file mode 100644 index 0000000..927588b --- /dev/null +++ b/scripts/plugin-hooks.test.mjs @@ -0,0 +1,80 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { cpSync, mkdtempSync, rmSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const windows = process.platform === 'win32'; +const shell = windows ? 'powershell' : 'bash'; +const directory = mkdtempSync(join(tmpdir(), 'managed apps hooks ')); +cpSync(join(root, 'plugins/microsoft-managed-apps/hooks'), join(directory, 'hooks'), { recursive: true }); +test.after(() => rmSync(directory, { recursive: true, force: true })); + +function run(name, input, host = 'copilot-cli') { + const env = { ...process.env }; + for (const key of ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'COPILOT_CLI', 'COPILOT_AGENT_SESSION_ID']) delete env[key]; + if (host === 'claude-code') env.CLAUDECODE = '1'; + if (host === 'copilot-cli') env.COPILOT_CLI = '1'; + const script = join(directory, 'hooks', `${name}.${windows ? 'ps1' : 'sh'}`); + const args = windows ? ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script] : [script]; + const result = spawnSync(shell, args, { env, input: `${JSON.stringify(input)}\n`, encoding: 'utf8', timeout: 10000 }); + assert.ifError(result.error); + assert.equal(result.status, 0, result.stderr); + return result.stdout.trim() ? JSON.parse(result.stdout) : undefined; +} + +for (const [host, payload] of [ + ['claude-code', command => ({ tool_name: windows ? 'powershell' : 'Bash', tool_input: { command, description: 'keep me' } })], + ['copilot-cli', command => ({ toolName: shell, toolArgs: { command, description: 'keep me' } })], +]) { + test(`${host}: attributes ms commands and preserves other arguments`, () => { + const result = run('pre-tool-use', payload('ms app list --json'), host); + assert.match(result.updatedInput.command, new RegExp(`plugin/${host}`)); + assert.equal(result.updatedInput.description, 'keep me'); + assert.deepEqual(result.modifiedArgs, result.updatedInput); + assert.deepEqual(result.hookSpecificOutput.updatedInput, result.updatedInput); + }); + + test(`${host}: leaves non-ms commands and explicit attribution unchanged`, () => { + const explicit = windows ? "$env:MS_CLI_ORIGIN = 'custom'; ms app list" : 'MS_CLI_ORIGIN=custom ms app list'; + for (const command of ['echo ms app list', 'node --version', explicit]) { + const result = run('pre-tool-use', payload(command), host); + assert.equal(result.updatedInput, undefined); + assert.equal(result.modifiedArgs, undefined); + } + }); + + test(`${host}: preserves inherited attribution at command execution`, () => { + const rewritten = run('pre-tool-use', payload('ms app list'), host).updatedInput.command; + const probe = windows + ? 'function ms { Write-Output $env:MS_CLI_ORIGIN }; ' + : 'ms() { printf "%s" "$MS_CLI_ORIGIN"; }; '; + for (const origin of [undefined, 'custom', '']) { + // Windows PowerShell 5.1 removes empty environment variables. + if (windows && origin === '') continue; + const env = { ...process.env }; + if (origin === undefined) delete env.MS_CLI_ORIGIN; + else env.MS_CLI_ORIGIN = origin; + const args = windows ? ['-NoProfile', '-Command', probe + rewritten] : ['-c', probe + rewritten]; + const result = spawnSync(shell, args, { env, encoding: 'utf8', timeout: 10000 }); + assert.ifError(result.error); + assert.equal(result.status, 0, result.stderr); + assert.equal(result.stdout.trim(), origin === undefined ? `plugin/${host}` : origin); + } + }); +} + +test('Copilot native bash input receives bash syntax even on Windows', () => { + const result = run('pre-tool-use', { toolName: 'bash', toolArgs: { command: 'ms app list' } }); + assert.match(result.modifiedArgs.command, /^export MS_CLI_ORIGIN=/); +}); + +test('session guidance supports both clients and skips compaction', () => { + const result = run('session-start', { source: 'startup' }); + assert.match(result.additionalContext, /MS_CLI_ORIGIN/); + assert.equal(result.hookSpecificOutput.additionalContext, result.additionalContext); + assert.equal(run('session-start', { source: 'compact' }), undefined); +}); diff --git a/scripts/requirements-plugin-validation.txt b/scripts/requirements-plugin-validation.txt new file mode 100644 index 0000000..e4787a5 --- /dev/null +++ b/scripts/requirements-plugin-validation.txt @@ -0,0 +1 @@ +skills-ref @ git+https://github.com/agentskills/agentskills.git@69ef37e9424c0a7ea9dd2293b559e43ec8176379#subdirectory=skills-ref diff --git a/scripts/validate-plugin-compatibility.mjs b/scripts/validate-plugin-compatibility.mjs new file mode 100644 index 0000000..f977848 --- /dev/null +++ b/scripts/validate-plugin-compatibility.mjs @@ -0,0 +1,166 @@ +import assert from 'node:assert/strict'; +import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'; +import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const pluginPath = 'plugins/microsoft-managed-apps'; +const schema = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json'; + +function isObject(value) { + return value !== null && typeof value === 'object' && !Array.isArray(value); +} + +function readJson(directory, path) { + const file = resolve(directory, path); + assert.ok(lstatSync(file).isFile(), `${path} must be a regular file, not a symlink`); + let value; + try { + value = JSON.parse(readFileSync(file, 'utf8')); + } catch (error) { + throw new Error(`${path}: ${error.message}`, { cause: error }); + } + assert.ok(isObject(value), `${path} must contain a JSON object`); + return value; +} + +function regularFile(plugin, path) { + const file = resolve(plugin, path); + const contained = relative(realpathSync(plugin), realpathSync(file)); + assert.ok(!isAbsolute(contained) && contained !== '..' && !contained.startsWith(`..${sep}`), + `${path} must remain inside the plugin`); + assert.ok(lstatSync(file).isFile(), `${path} must be a regular file, not a symlink`); + return readFileSync(file, 'utf8').replaceAll('\r\n', '\n'); +} + +function validateComponents(directory) { + const plugin = resolve(directory, pluginPath); + const agent = 'microsoft-apps-architect'; + assert.deepEqual(readdirSync(resolve(plugin, 'agents')).sort(), [`${agent}.md`], + 'legacy architect agent must remain discoverable'); + assert.deepEqual(readdirSync(resolve(plugin, 'com.github.copilot/agents')).sort(), [`${agent}.agent.md`], + 'Copilot architect agent must remain discoverable without duplicates'); + assert.equal(regularFile(plugin, `com.github.copilot/agents/${agent}.agent.md`), + regularFile(plugin, `agents/${agent}.md`).replaceAll('../shared/', '../../shared/').replaceAll('../skills/', '../../skills/'), + 'Copilot agent must match the legacy agent except for relative resource paths'); + + const legacy = readJson(directory, `${pluginPath}/hooks/hooks.json`); + assert.deepEqual(Object.keys(legacy.hooks).sort(), ['PreToolUse', 'SessionStart'], + 'preserve both legacy attribution hooks'); + const hooks = {}; + for (const [event, name] of [['SessionStart', 'sessionStart'], ['PreToolUse', 'preToolUse']]) { + assert.equal(legacy.hooks[event].length, 1, `preserve one ${event} matcher`); + const group = legacy.hooks[event][0]; + hooks[name] = group.hooks.map(hook => { + for (const command of [hook.command, hook.bash, hook.powershell]) { + assert.equal(typeof command, 'string', `${event} must support both shells`); + const matches = [...command.matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([^"]+)/g)]; + assert.equal(matches.length, 1, `${event} must use a plugin-root script path`); + regularFile(plugin, matches[0][1]); + } + return { + type: hook.type, + ...(event === 'PreToolUse' ? { matcher: group.matcher } : {}), + bash: hook.bash.replaceAll('${CLAUDE_PLUGIN_ROOT}', '${PLUGIN_ROOT}'), + powershell: hook.powershell.replaceAll('${CLAUDE_PLUGIN_ROOT}', '${PLUGIN_ROOT}'), + env: { COPILOT_CLI: '1' }, + timeoutSec: hook.timeoutSec, + }; + }); + assert.equal(hooks[name].length, 1, `preserve one ${event} command`); + } + const copilot = readJson(directory, `${pluginPath}/com.github.copilot/hooks/hooks.json`); + assert.deepEqual(copilot, { version: 1, hooks }, + 'Copilot hooks must match the legacy scripts, matchers, and timeouts with native root paths'); + + for (const base of ['skills', 'shared', 'agents', 'com.github.copilot/agents']) { + const visit = folder => { + assert.ok(lstatSync(folder).isDirectory(), `${folder} must be a regular directory, not a symlink`); + for (const entry of readdirSync(folder, { withFileTypes: true })) { + const file = resolve(folder, entry.name); + assert.ok(!entry.isSymbolicLink(), `${file} must not be a symlink`); + if (entry.isDirectory()) visit(file); + else if (entry.name.endsWith('.md')) { + const text = regularFile(plugin, relative(plugin, file)); + assert.ok(!/\$\{(?:CLAUDE_)?PLUGIN_ROOT\}/.test(text), + `${relative(plugin, file)} must use document-relative resource paths`); + for (const [, target] of text.matchAll(/\]\(([^)\s]+)\)/g)) { + if (!target.startsWith('./') && !target.startsWith('../')) continue; + regularFile(plugin, relative(plugin, resolve(dirname(file), target.split('#')[0]))); + } + } + } + }; + visit(resolve(plugin, base)); + } +} + +// Agent Plugins 1.0.0 has a small, closed manifest schema. +function validateManifest(manifest) { + assert.equal(manifest.$schema, schema, 'plugin.json must declare the Agent Plugins 1.0.0 schema'); + assert.equal(typeof manifest.name, 'string', 'plugin.json name must be a string'); + assert.ok(manifest.name.length <= 64, 'plugin.json name must not exceed 64 characters'); + assert.match(manifest.name, /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/, 'invalid plugin.json name'); + + const strings = ['version', 'description', 'homepage', 'repository', 'license']; + const fields = ['$schema', 'name', ...strings, 'author', 'keywords', 'extensions']; + for (const key of Object.keys(manifest)) { + assert.ok(fields.includes(key), `plugin.json has an unknown field: ${key}`); + } + for (const key of strings) { + if (key in manifest) assert.equal(typeof manifest[key], 'string', `plugin.json ${key} must be a string`); + } + if ('author' in manifest) { + assert.ok(isObject(manifest.author), 'plugin.json author must be an object'); + for (const [key, value] of Object.entries(manifest.author)) { + assert.ok(['name', 'email', 'url'].includes(key), `plugin.json author has an unknown field: ${key}`); + assert.equal(typeof value, 'string', `plugin.json author.${key} must be a string`); + } + } + if ('keywords' in manifest) { + assert.ok(Array.isArray(manifest.keywords), 'plugin.json keywords must be an array'); + assert.ok(manifest.keywords.every(value => typeof value === 'string'), 'plugin.json keywords must contain strings'); + } + if ('extensions' in manifest) { + assert.ok(isObject(manifest.extensions), 'plugin.json extensions must be an object'); + assert.ok(Object.values(manifest.extensions).every(isObject), 'plugin.json extension values must be objects'); + } +} + +export function validate(directory = root) { + const canonical = readJson(directory, `${pluginPath}/plugin.json`); + const legacy = readJson(directory, `${pluginPath}/.claude-plugin/plugin.json`); + validateManifest(canonical); + const { $schema, ...metadata } = canonical; + assert.deepEqual(legacy, metadata, 'legacy plugin.json must match the canonical manifest except for $schema'); + + const marketplace = readJson(directory, '.claude-plugin/marketplace.json'); + assert.equal(marketplace.name, 'Managed-Apps', 'preserve the existing marketplace identity'); + assert.ok(Array.isArray(marketplace.plugins), 'legacy marketplace plugins must be an array'); + const entries = marketplace.plugins.filter(entry => entry?.name === canonical.name); + assert.equal(entries.length, 1, 'legacy marketplace must contain exactly one matching plugin'); + assert.equal(canonical.name, 'microsoft-managed-apps', 'preserve the existing plugin identity'); + assert.equal(entries[0].source, `./${pluginPath}`, 'preserve the existing plugin source path'); + for (const key of ['version', 'description']) { + assert.equal(typeof canonical[key], 'string', `this plugin must declare ${key}`); + assert.equal(entries[0][key], canonical[key], `legacy marketplace ${key} must match plugin.json`); + } + + const codex = readJson(directory, '.agents/plugins/marketplace.json'); + assert.equal(codex.name, marketplace.name, 'marketplace identities must match'); + assert.ok(Array.isArray(codex.plugins), 'Codex marketplace plugins must be an array'); + const codexEntries = codex.plugins.filter(entry => entry?.name === canonical.name); + assert.equal(codexEntries.length, 1, 'Codex marketplace must contain exactly one matching plugin'); + assert.deepEqual(codexEntries[0].source, { source: 'local', path: `./${pluginPath}` }, 'Codex must use the same plugin directory'); + validateComponents(directory); +} + +if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { + try { + validate(); + console.log('Plugin manifests, components, and resource paths are compatible.'); + } catch (error) { + console.error(`Plugin compatibility check failed: ${error.message}`); + process.exitCode = 1; + } +} diff --git a/scripts/validate-plugin-compatibility.test.mjs b/scripts/validate-plugin-compatibility.test.mjs new file mode 100644 index 0000000..1845c5b --- /dev/null +++ b/scripts/validate-plugin-compatibility.test.mjs @@ -0,0 +1,146 @@ +import assert from 'node:assert/strict'; +import { copyFileSync, cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import test from 'node:test'; +import { validate } from './validate-plugin-compatibility.mjs'; + +const root = resolve(dirname(fileURLToPath(import.meta.url)), '..'); +const canonical = 'plugins/microsoft-managed-apps/plugin.json'; +const legacy = 'plugins/microsoft-managed-apps/.claude-plugin/plugin.json'; +const marketplace = '.claude-plugin/marketplace.json'; +const codex = '.agents/plugins/marketplace.json'; + +function fixture(t) { + const directory = mkdtempSync(join(tmpdir(), 'managed-apps-compatibility-')); + t.after(() => rmSync(directory, { recursive: true, force: true })); + for (const path of [canonical, legacy, marketplace, codex]) { + mkdirSync(dirname(join(directory, path)), { recursive: true }); + copyFileSync(join(root, path), join(directory, path)); + } + for (const path of ['agents', 'hooks', 'com.github.copilot', 'skills', 'shared']) { + cpSync(join(root, 'plugins/microsoft-managed-apps', path), + join(directory, 'plugins/microsoft-managed-apps', path), { recursive: true }); + } + return directory; +} + +function edit(directory, path, change) { + const file = join(directory, path); + const value = JSON.parse(readFileSync(file, 'utf8')); + change(value); + writeFileSync(file, JSON.stringify(value)); +} + +test('repository manifests pass', () => validate()); + +test('comparison ignores formatting and object key order', t => { + const directory = fixture(t); + const file = join(directory, legacy); + const value = JSON.parse(readFileSync(file, 'utf8')); + value.author = Object.fromEntries(Object.entries(value.author).reverse()); + writeFileSync(file, JSON.stringify(Object.fromEntries(Object.entries(value).reverse()))); + validate(directory); +}); + +for (const [name, path, change, message] of [ + ['legacy version drift', legacy, value => { value.version = '0.0.0'; }, /legacy plugin.json must match/], + ['nested metadata drift', legacy, value => { value.author.name = 'Changed'; }, /legacy plugin.json must match/], + ['missing schema', canonical, value => { delete value.$schema; }, /must declare/], + ['unsupported schema', canonical, value => { value.$schema = 'https://example.com/schema'; }, /must declare/], + ['unexpected legacy schema', legacy, value => { value.$schema = 'extra'; }, /legacy plugin.json must match/], + ['invalid name', canonical, value => { value.name = 'invalid--name'; }, /invalid plugin.json name/], + ['unknown field', canonical, value => { value.skills = './skills'; }, /unknown field/], + ['invalid metadata type', canonical, value => { value.version = 1; }, /version must be a string/], + ['invalid author field', canonical, value => { value.author.extra = 'x'; }, /author has an unknown field/], + ['invalid keyword', canonical, value => { value.keywords = [1]; }, /keywords must contain strings/], + ['invalid extensions', canonical, value => { value.extensions = { 'com.example': [] }; }, /extension values must be objects/], + ['marketplace version drift', marketplace, value => { value.plugins[0].version = '0.0.0'; }, /marketplace version must match/], + ['marketplace source drift', marketplace, value => { value.plugins[0].source = './wrong'; }, /source path/], + ['missing marketplace entry', marketplace, value => { value.plugins = []; }, /exactly one matching plugin/], + ['duplicate marketplace entry', marketplace, value => { value.plugins.push(value.plugins[0]); }, /exactly one matching plugin/], + ['Codex source drift', codex, value => { value.plugins[0].source.path = './wrong'; }, /same plugin directory/], + ['Codex marketplace identity drift', codex, value => { value.name = 'different'; }, /marketplace identities must match/], + ['duplicate Codex marketplace entry', codex, value => { value.plugins.push(value.plugins[0]); }, /exactly one matching plugin/], +]) { + test(`rejects ${name}`, t => { + const directory = fixture(t); + edit(directory, path, change); + assert.throws(() => validate(directory), message); + }); +} + +for (const path of [canonical, legacy, marketplace, codex]) { + test(`rejects malformed JSON: ${path}`, t => { + const directory = fixture(t); + writeFileSync(join(directory, path), '../plugin.json'); + assert.throws(() => validate(directory), /Unexpected token/); + }); + + test(`rejects a non-object: ${path}`, t => { + const directory = fixture(t); + writeFileSync(join(directory, path), 'null'); + assert.throws(() => validate(directory), /must contain a JSON object/); + }); + + test(`rejects a missing file: ${path}`, t => { + const directory = fixture(t); + rmSync(join(directory, path)); + assert.throws(() => validate(directory), /ENOENT/); + }); + + test(`rejects a symlink: ${path}`, t => { + const directory = fixture(t); + const file = join(directory, path); + const target = join(directory, 'target.json'); + copyFileSync(file, target); + rmSync(file); + try { + symlinkSync(target, file, 'file'); + } catch (error) { + if (process.platform !== 'win32' || error.code !== 'EPERM') throw error; + t.skip('Windows requires permission to create file symlinks. Linux CI covers this case.'); + return; + } + + assert.throws(() => validate(directory), /must be a regular file/); + }); +} + +test('rejects a missing Copilot agent', t => { + const directory = fixture(t); + rmSync(join(directory, 'plugins/microsoft-managed-apps/com.github.copilot/agents/microsoft-apps-architect.agent.md')); + assert.throws(() => validate(directory), /Copilot architect agent/); +}); + +test('rejects Copilot agent drift', t => { + const directory = fixture(t); + writeFileSync(join(directory, 'plugins/microsoft-managed-apps/com.github.copilot/agents/microsoft-apps-architect.agent.md'), 'changed'); + assert.throws(() => validate(directory), /Copilot agent must match/); +}); + +test('rejects Copilot hook drift', t => { + const directory = fixture(t); + edit(directory, 'plugins/microsoft-managed-apps/com.github.copilot/hooks/hooks.json', + value => { value.hooks.preToolUse[0].bash = 'wrong'; }); + assert.throws(() => validate(directory), /Copilot hooks must match/); +}); + +test('rejects missing hook scripts', t => { + const directory = fixture(t); + rmSync(join(directory, 'plugins/microsoft-managed-apps/hooks/pre-tool-use.ps1')); + assert.throws(() => validate(directory), /ENOENT/); +}); + +for (const [name, content, message] of [ + ['host-specific root', '[shared](${CLAUDE_PLUGIN_ROOT}/shared/shared-instructions.md)', /document-relative/], + ['missing resource', '[shared](../../shared/missing.md)', /ENOENT/], + ['escaping resource', '[outside](../../../../.claude-plugin/marketplace.json)', /inside the plugin/], +]) { + test(`rejects ${name} in a skill`, t => { + const directory = fixture(t); + writeFileSync(join(directory, 'plugins/microsoft-managed-apps/skills/create-app/SKILL.md'), content); + assert.throws(() => validate(directory), message); + }); +} diff --git a/scripts/validate_plugin_skills.py b/scripts/validate_plugin_skills.py new file mode 100644 index 0000000..6fb9294 --- /dev/null +++ b/scripts/validate_plugin_skills.py @@ -0,0 +1,52 @@ +"""Validate every packaged skill with the pinned Agent Skills reference library.""" + +import sys +from pathlib import Path + +from skills_ref.errors import ParseError +from skills_ref.parser import parse_frontmatter +from skills_ref.validator import validate_metadata + + +def validate_skills(plugin: Path) -> list[str]: + errors = [] + skills = sorted(path for path in (plugin / "skills").iterdir() if path.is_dir()) + if not skills: + return ["skills: at least one packaged skill is required"] + for skill in skills: + file = skill / "SKILL.md" + if not file.is_file(): + errors.append(f"{skill.name}: missing SKILL.md") + continue + try: + metadata, _ = parse_frontmatter(file.read_text(encoding="utf-8")) + except ParseError as error: + errors.append(f"{skill.name}: {error}") + continue + skill_errors = validate_metadata(metadata, skill) + for error in skill_errors: + errors.append(f"{skill.name}: {error}") + if skill_errors: + continue + # The reference library does not check types for every optional field. + for field in ("license", "allowed-tools"): + if field in metadata and not isinstance(metadata[field], str): + errors.append(f"{skill.name}: {field} must be a string") + if "metadata" in metadata: + value = metadata["metadata"] + if not isinstance(value, dict) or not all( + isinstance(key, str) and isinstance(item, str) for key, item in value.items() + ): + errors.append(f"{skill.name}: metadata must map strings to strings") + if "compatibility" in metadata and not metadata["compatibility"].strip(): + errors.append(f"{skill.name}: compatibility must not be empty") + return errors + + +if __name__ == "__main__": + plugin = Path(__file__).resolve().parents[1] / "plugins" / "microsoft-managed-apps" + errors = validate_skills(plugin) + if errors: + print("\n".join(errors), file=sys.stderr) + sys.exit(1) + print("All packaged skills conform to the Agent Skills specification.") diff --git a/scripts/validate_plugin_skills_test.py b/scripts/validate_plugin_skills_test.py new file mode 100644 index 0000000..0e5e0e0 --- /dev/null +++ b/scripts/validate_plugin_skills_test.py @@ -0,0 +1,57 @@ +import tempfile +import unittest +from pathlib import Path + +from validate_plugin_skills import validate_skills + + +class SkillValidationTests(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.plugin = Path(self.directory.name) + self.skill = self.plugin / "skills" / "example" + self.skill.mkdir(parents=True) + + def write_skill(self, extra="", name="example", description="Example skill."): + (self.skill / "SKILL.md").write_text( + f"---\nname: {name}\ndescription: {description}\n{extra}---\nInstructions.\n", + encoding="utf-8", + ) + + def test_valid_portable_skill(self): + self.write_skill('allowed-tools: Read Edit\nmetadata:\n author: Microsoft\n') + self.assertEqual(validate_skills(self.plugin), []) + + def test_invalid_skills(self): + for extra, name, description in [ + ("model: opus\n", "example", "Example."), + ("user-invocable: true\n", "example", "Example."), + ("", "different-name", "Example."), + ("", "example", "x" * 1025), + ('compatibility: ""\n', "example", "Example."), + ("metadata: invalid\n", "example", "Example."), + ("allowed-tools: [Read, Edit]\n", "example", "Example."), + ]: + with self.subTest(extra=extra, name=name): + self.write_skill(extra, name, description) + self.assertTrue(validate_skills(self.plugin)) + + def test_missing_and_malformed_frontmatter(self): + for content in ["Instructions.", "---\nname: [\n---\nInstructions."]: + with self.subTest(content=content): + (self.skill / "SKILL.md").write_text(content, encoding="utf-8") + self.assertTrue(validate_skills(self.plugin)) + + def test_checks_every_immediate_skill(self): + self.write_skill() + (self.plugin / "skills" / "missing").mkdir() + self.assertTrue(validate_skills(self.plugin)) + + def test_empty_package(self): + self.skill.rmdir() + self.assertTrue(validate_skills(self.plugin)) + + +if __name__ == "__main__": + unittest.main()