doc: plugin structure doc

[JasonYeMSFT (JasonYeMSFT)]

Description

• Update onboarding doc for new plugin folder structure
• Document plugin folder structure
• Document nuances in plugin manifest and hooks

Checklist

• Tests pass locally (cd tests && npm test)
• Title has one of the prefixes: fix:, feat:, feature:, chore:, misc:, test:, eval:
• If modifying skill descriptions: verified routing correctness with integration tests (In tests/, npm run test:integration -- <skill> or npm run test:vally -- --skill <skill>)

Related Issues

[Copilot]

Pull request overview

This PR updates repository documentation to describe a (proposed) new plugin folder structure, including additional docs for plugin manifests and hooks, and adjusts onboarding/versioning guidance accordingly.

Changes:

• Update versioning documentation to reference a plugins/<plugin>/... layout.
• Add new docs explaining plugin manifests (docs/plugin-manifest.md) and hooks (docs/hooks.md).
• Update onboarding instructions to reference the new structure and revised local testing commands.

Show a summary per file

File	Description
docs/VERSIONING.md	Updates version-stamping and changelog trigger docs to the new plugins/<plugin> paths.
docs/plugin-manifest.md	New doc describing client-specific plugin manifests and hooks manifest relationships.
docs/Onboarding.md	Updates onboarding guidance and examples to the new multi-plugin directory structure and output paths.
docs/hooks.md	New doc explaining hooks manifests and how different clients consume them.

Review details

Comments suppressed due to low confidence (13)

docs/VERSIONING.md:24

• The changelog criteria are incomplete and also point to the wrong directory. generateChangelog() explicitly filters to commits that touch plugin/ and whose subjects start with specific prefixes (see gulpfile.ts:248-252).

The `CHANGELOG.md` is automatically generated at build time by the Gulp pipeline. It includes merged PRs that:
- Touch the `plugins/<plugin>` directory

docs/VERSIONING.md:40

• This bullet claims plugin versions update for files under plugins/, but the repo currently tracks plugin version changes under plugin/ (see gulpfile.ts:115-118).

### Files That Trigger Version Updates:
- ✅ Any file under `plugins/` folder (for plugin version)

docs/plugin-manifest.md:15

• The Copilot CLI / VS Code sections currently state the .plugin/plugin.json "references" a hooks manifest, but plugin/.plugin/plugin.json has no hooks property; it relies on the default hooks/hooks.json (see plugin/.plugin/plugin.json and plugin/hooks/hooks.json). Also the VS Code section mistakenly starts with “Copilot CLI”.

Copilot CLI looks for the `.plugin/plugin.json` file. It references a hooks manifest shared with VS Code.

## VS Code

Copilot CLI looks for the `.plugin/plugin.json` file. It references a hooks manifest shared with Copilot CLI.

docs/plugin-manifest.md:23

• Typo: “This log is not required …” should be “logo”. Also “in its website” is ungrammatical.

Cursor looks for the `.cursor-plugin/plugin.json`. It references a dedicated `cursor-hooks.json` hooks manifest. It also has a `logo` property referencing an image file. Cursor marketplace presents the [azure](https://cursor.com/marketplace/azure) plugin with the icon in its website. This log is not required if the plugin is not onboarded to the official Cursor marketplace.

docs/Onboarding.md:64

• Typos/incorrect paths: the doc refers to plugins/<your-plugin-name>/ and .calude-plugin/, but the repo structure is plugin/ and the directory is .claude-plugin/.

Each plugin has all its files stored under `plugins/<your-plugin-name>/`, called the plugin root. `plugins/azure-skills/` is a well established plugin you can use as an example.

`.calude-plugin/` contains the plugin manifest for Claude Code. `.cursor-plugin/` contains the plugin manifest for Cursor. `.plugin/` contains the plugin manifest for Copilot CLI and VS Code. We have to maintain separate plugin manifests because clients use them in different ways. See [plugin-manifest.md](./plugin-manifest.md) for more explanation. Every new plugin should at least provide these manifests to make sure it works for these clients.

docs/Onboarding.md:75

• npm run plugin:new is documented here, but there is no plugin:new script in the repo’s package.json. This will fail for readers following the onboarding steps.

You run this command at the repository root and scaffold a new plugin following the instructions.

```bash
npm run plugin:new

**docs/Onboarding.md:93**
* This step points readers to create skills under `plugins/<plugin>/...`, but the current repo structure uses `plugin/skills/...`.

1. Create your skill folder under plugins/<plugin>/skills/your-skill-name/

**docs/Onboarding.md:142**
* The build copies `plugin/` contents directly into `output/` (see `gulpfile.ts:113-119`), so `copilot --plugin-dir ./output/<plugin>` will not resolve in this repo layout.

copilot --plugin-dir ./output/

**docs/Onboarding.md:151**
* These instructions reference `plugins/<plugin>/skills` and `output/<plugin>`, but the current repo uses `plugin/` and builds into `output/` (see `gulpfile.ts:113-119`).

After making changes to skill files under plugins/<plugin>/skills:

1. Rebuild the plugin to update the output/<plugin> directory:

   npm run build

**docs/Onboarding.md:166**
* The Vally lint command now points at `plugins/`, which doesn’t exist in the current repo layout. Existing skills are under `plugin/skills/`.

npx --yes @microsoft/vally-cli@^0.7.0 lint plugins/ --eval-spec evals/ --strict --grader-plugin ./tests/vally/vally-graders.ts

**docs/Onboarding.md:49**
* The directory tree is currently rendered as siblings of `plugins/` (and references `azure-skills/` under the repo root). If you’re describing the current repo layout, these entries should be nested under `plugin/` instead.

/
├── plugins/
├── azure-skills/ (existing plugin)
├── / (your new plugin)
├── .claude-plugin/ (claude code plugin manifest)

**docs/Onboarding.md:79**
* This sentence references `plugins/<plugin>/skills`, but the repo’s pre-built skills are currently under `plugin/skills/`.

Skills in this repo are organized in agent plugins. Pre-built skills are located under plugins/<plugin>/skills. Each skill folder contains:

**docs/Onboarding.md:82**
* This example path uses `plugins/<plugin>/...`, but the current repo path is under `plugin/skills/...`.

plugins//skills/your-skill-name/

</details>


- **Files reviewed:** 4/4 changed files
- **Comments generated:** 4
- **Review effort level:** Low

[JasonYeMSFT (JasonYeMSFT)]

The path changes are for an upcoming change.