clean skills

Author: KSemenenko

.github/upstream-watch.official-skills.json

@@ -7,7 +7,7 @@
       "name": "dotnet/skills main branch",
       "issue_key": "official-dotnet-skills-upstream",
       "issue_name": "Review official dotnet/skills upstream update",
-      "notes": "Review vendir.lock.yml, sync upstreams/dotnet-skills via vendir, rerun scripts/import_external_catalog_sources.py, then regenerate catalog outputs and verify the imported official skills and agents.",
+      "notes": "Review external-sources/vendir.lock.yml, sync external-sources/upstreams/dotnet-skills via vendir, rerun scripts/import_external_catalog_sources.py, then regenerate catalog outputs and verify the imported official skills and agents.",
       "skills": [
         "configuring-opentelemetry-dotnet",
         "minimal-api-file-upload",

.github/workflows/catalog-check.yml

@@ -17,17 +17,23 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Install vendir
+        run: |
+          mkdir -p .tools
+          curl -fsSL https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR="$PWD/.tools" bash
+          echo "$PWD/.tools" >> "$GITHUB_PATH"
+
       - name: Validate automation scripts
         run: python3 -m py_compile scripts/generate_catalog.py scripts/generate_catalog_definitions.py scripts/generate_agent_catalog.py scripts/generate_release_notes.py scripts/import_external_catalog_sources.py scripts/upstream_watch.py
 
       - name: Validate external catalog source config
         run: python3 scripts/import_external_catalog_sources.py --validate-config
 
-      - name: Normalize vendored external sources
-        run: python3 scripts/import_external_catalog_sources.py
+      - name: Sync and normalize external sources
+        run: bash scripts/sync_external_catalog_sources.sh
 
       - name: Verify imported external sources are committed
-        run: git diff --exit-code -- catalog
+        run: git diff --exit-code -- catalog external-sources
 
       - name: Validate catalog source metadata
         run: |

AGENTS.md

@@ -30,12 +30,11 @@ Follow official or documented agent standards where they exist; do not present a
 - Areas with specialized responsibilities:
   - `agents/`: top-level orchestration agents that sit above the skill catalog, one folder per agent
   - `catalog/`: canonical scanned catalog tree, including package manifests plus nested skills and package-owned agents
-  - `catalog-sources/`: mapping files for vendir-managed external repositories that are normalized into `catalog/`
+  - `external-sources/`: vendir transport config, pinned lockfile, checked-in upstream snapshots, and import overrides for external repositories
   - `cli/ManagedCode.DotnetAgents/`: publishable `dotnet-agents` installer tool for repo-owned orchestration agents
   - `cli/ManagedCode.Agents/`: publishable `agents` installer tool for the same repo-owned orchestration agents
   - `cli/ManagedCode.DotnetSkills/`: publishable `dotnet-skills` installer tool
   - `scripts/`: catalog generation and upstream-watch automation
-  - `upstreams/`: vendir-managed checked-in snapshots of external source repositories
   - `.github/workflows/`: CI, release, and scheduled automation
 - Local `AGENTS.md` files currently present: none
 
@@ -80,10 +79,12 @@ Treat explicit frustration, swearing, sarcasm, repeated rejection, or "don't do
 - Skill- or agent-specific manifest metadata belongs in the nearest sibling `manifest.json` next to that `SKILL.md` or `AGENT.md`, not in package-level keyed maps and not in `SKILL.md` frontmatter. For skills, keep `version`, `category`, `packages`, and `package_prefix` in that sibling manifest. Keep package `manifest.json` for package-level metadata such as title, icon, and upstream links.
 - Package `manifest.json` should also hold upstream source metadata for the package surface: repository URL plus docs and NuGet links when known. Catalog generators should read those links from manifests and propagate them into exported catalog data and the public site instead of hardcoding or inferring them ad hoc.
 - Do not hardcode catalog category lists or catalog type-directory lists as root constants in Python or C#. Derive them from the scanned catalog or a generated artifact sourced from the catalog manifests, so adding a new manifest category or catalog type does not require manual constant edits in runtime code.
-- External repositories that contribute skills or agents must be synced declaratively via `vendir.yml` and pinned in `vendir.lock.yml`, with checked-in snapshots under `upstreams/`. Do not copy external repositories into `catalog/` by hand.
-- Normalize vendir-managed upstream content into `catalog/` through a repo script and a checked-in config under `catalog-sources/`, so multiple repositories can be imported consistently.
+- External repositories that contribute skills or agents must live under `external-sources/`: keep vendir transport config in `external-sources/vendir.yml`, the lockfile in `external-sources/vendir.lock.yml`, and checked-in upstream snapshots under `external-sources/upstreams/`. Do not copy external repositories into `catalog/` by hand.
+- Normalize vendir-managed upstream content into `catalog/` through `scripts/import_external_catalog_sources.py` plus checked-in overrides under `external-sources/imports/`.
+- Import configs under `external-sources/imports/` are overrides-only. Auto-discover upstream plugins from vendored `plugin.json` files instead of maintaining a second manual plugin registry in local config.
 - Imported official upstream skills or agents may keep their upstream canonical ids instead of being renamed to fit the local `dotnet-*` convention.
 - If an imported official upstream skill or agent is a true duplicate of a repo-authored local entry, prefer the official upstream source and remove the local duplicate instead of keeping two copies.
+- Do not inject HTML provenance comments such as `Imported from ... via vendir` into generated `SKILL.md` or `AGENT.md` files. Keep imported content clean; provenance belongs in package metadata, external-source config, or importer logic, not inside the skill or agent body.
 
 ### Issue Workflow
 
@@ -179,13 +180,14 @@ Other important repository files:
 - [`README.md`](README.md): public catalog and repository overview.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md): contributor workflow for skills, versions, descriptions, and watch entries.
 - [`agents/README.md`](agents/README.md): index of repo-owned orchestration agents and layout conventions.
-- [`catalog-sources/*.json`](catalog-sources/): source-import mapping files that describe how vendir-managed repositories are converted into catalog packages.
+- [`external-sources/`](external-sources/): dedicated area for vendir transport config, vendored upstream snapshots, and import overrides.
+- [`external-sources/imports/*.json`](external-sources/imports/): overrides-only import policy files for vendir-managed repositories.
 - [`catalog/*/*/manifest.json`](catalog/): package manifests that hold package metadata and upstream links for the scanned catalog tree.
 - [`catalog/*/*/skills/*/manifest.json`](catalog/): sibling skill manifests that hold skill-specific metadata such as `version`, `category`, `packages`, and `package_prefix`.
 - [`catalog/*/*/agents/*/manifest.json`](catalog/): sibling agent manifests for agent-specific metadata when needed.
-- [`upstreams/`](upstreams): vendir-managed snapshots of external source repositories used by import scripts.
-- [`vendir.yml`](vendir.yml): declarative source-sync config for vendir-managed repositories.
-- [`vendir.lock.yml`](vendir.lock.yml): resolved vendir lock file with pinned upstream SHAs.
+- [`external-sources/upstreams/`](external-sources/upstreams/): vendir-managed snapshots of external source repositories used by import scripts.
+- [`external-sources/vendir.yml`](external-sources/vendir.yml): declarative source-sync config for vendir-managed repositories.
+- [`external-sources/vendir.lock.yml`](external-sources/vendir.lock.yml): resolved vendir lock file with pinned upstream SHAs.
 - [`.github/workflows/catalog-check.yml`](.github/workflows/catalog-check.yml): pull-request validation workflow for generated catalog outputs and tool smoke checks.
 - [`.github/workflows/publish-catalog.yml`](.github/workflows/publish-catalog.yml): unified 04:00 UTC release workflow for `catalog-v*` assets, NuGet tool publish, and GitHub Pages deployment.
 - [`.github/upstream-watch.json`](.github/upstream-watch.json): base upstream watch metadata file for labels and shared defaults.

CONTRIBUTING.md

@@ -206,11 +206,14 @@ Do not introduce or treat a checked-in aggregate catalog JSON file as the canoni
 
 External upstream repositories are handled separately:
 
-- `vendir.yml` declares which repositories are synced into `upstreams/`
-- `vendir.lock.yml` pins the resolved upstream SHAs
-- `catalog-sources/*.json` describes how vendored upstream plugins are normalized into `catalog/<type>/<package>/`
+- `external-sources/vendir.yml` declares which repositories are synced into `external-sources/upstreams/`
+- `external-sources/vendir.lock.yml` pins the resolved upstream SHAs
+- `external-sources/imports/*.json` carries overrides-only import policy for vendored upstream plugins
 - `scripts/import_external_catalog_sources.py` performs the normalization step
 
+Do not maintain a second manual plugin registry in local config.
+The importer auto-discovers upstream plugins from vendored `plugin.json` files and uses `external-sources/imports/*.json` only for local policy such as type, category, package naming, compatibility, and skill-level package trigger overrides.
+
 For imported official upstream skills, keep the upstream skill or agent id unless there is a real compatibility reason to rename it.
 
 Do not hand-edit the generated catalog tables.

README.md

@@ -179,12 +179,14 @@ catalog/
         ├── skills/
         │   └── <skill-name>/
         │       ├── SKILL.md
+        │       ├── manifest.json
         │       ├── scripts/     # optional
         │       ├── references/  # optional
         │       └── assets/      # optional
         └── agents/
             └── <agent-name>/
                 ├── AGENT.md
+                ├── manifest.json # optional
                 ├── scripts/     # optional
                 ├── references/  # optional
                 └── assets/      # optional
@@ -194,7 +196,25 @@ The package-level `manifest.json` is the package control plane. It carries packa
 
 `SKILL.md` should stay focused on routing, workflow, deliverables, and validation. Do not put `version`, `category`, `packages`, or `package_prefix` in `SKILL.md` frontmatter.
 
-External upstream repositories are vendir-managed under `upstreams/`, mapped by `catalog-sources/*.json`, and normalized into `catalog/` by `scripts/import_external_catalog_sources.py`. Official imports may keep their upstream skill ids instead of being renamed to `dotnet-*`.
+## External Upstream Sources
+
+External upstream repositories live in the dedicated [`external-sources/`](external-sources/) area.
+
+- `external-sources/vendir.yml` and `external-sources/vendir.lock.yml` handle fetch-and-pin only.
+- `external-sources/upstreams/` holds the checked-in vendored snapshots.
+- `external-sources/imports/*.json` is overrides-only local policy for type, category, package naming, compatibility, and skill-level package trigger metadata.
+- `scripts/import_external_catalog_sources.py` auto-discovers upstream plugins from vendored `plugin.json` files, applies the local overrides, and normalizes the result into `catalog/<type>/<package>/`.
+
+Official imports may keep their upstream skill ids instead of being renamed to `dotnet-*`.
+
+```mermaid
+flowchart LR
+  A["external-sources/vendir.yml"] --> B["external-sources/upstreams/<repo>/"]
+  B --> C["plugin.json auto-discovery"]
+  D["external-sources/imports/*.json (overrides only)"] --> C
+  C --> E["scripts/import_external_catalog_sources.py"]
+  E --> F["catalog/<type>/<package>/"]
+```
 
 When you refresh vendored upstream content locally, use `bash scripts/sync_external_catalog_sources.sh`.
 

catalog/Frameworks/Official-DotNet-ASPNet/skills/configuring-opentelemetry-dotnet/SKILL.md

@@ -3,8 +3,6 @@ name: configuring-opentelemetry-dotnet
 description: "Configure OpenTelemetry distributed tracing, metrics, and logging in ASP.NET Core using the .NET OpenTelemetry SDK. Use when adding observability, setting up OTLP exporters, creating custom metrics/spans, or troubleshooting distributed trace correlation."
 compatibility: "Requires an ASP.NET Core project or solution."
 ---
-
-<!-- Imported from upstreams/dotnet-skills/dotnet-aspnet/skills/configuring-opentelemetry-dotnet/SKILL.md via vendir. Edit upstream or catalog-sources config, then rerun scripts/import_external_catalog_sources.py. -->
 # Configuring OpenTelemetry in .NET
 
 ## When to Use

catalog/Frameworks/Official-DotNet-ASPNet/skills/minimal-api-file-upload/SKILL.md

@@ -3,8 +3,6 @@ name: minimal-api-file-upload
 description: "File upload endpoints in ASP.NET minimal APIs (.NET 8+)"
 compatibility: "Requires an ASP.NET Core project or solution."
 ---
-
-<!-- Imported from upstreams/dotnet-skills/dotnet-aspnet/skills/minimal-api-file-upload/SKILL.md via vendir. Edit upstream or catalog-sources config, then rerun scripts/import_external_catalog_sources.py. -->
 # Implementing File Uploads in ASP.NET Core Minimal APIs
 
 ## When to Use

catalog/Frameworks/Official-DotNet-MAUI/skills/dotnet-maui-doctor/SKILL.md

@@ -3,8 +3,6 @@ name: dotnet-maui-doctor
 description: "Diagnoses and fixes .NET MAUI development environment issues. Validates .NET SDK, workloads, Java JDK, Android SDK, Xcode, and Windows SDK. All version requirements discovered dynamically from NuGet WorkloadDependencies.json — never hardcoded. Use when: setting up MAUI development, build errors mentioning SDK/workload/JDK/Android, \"Android SDK not found\", \"Java version\" errors, \"Xcode not found\", environment verification after updates, or any MAUI toolchain issues. Do not use for: non-MAUI .NET projects, Xamarin.Forms apps, runtime app crashes unrelated to environment setup, or app store publishing issues. Works on macOS, Windows, and Linux."
 compatibility: "Requires a .NET MAUI project or solution."
 ---
-
-<!-- Imported from upstreams/dotnet-skills/dotnet-maui/skills/dotnet-maui-doctor/SKILL.md via vendir. Edit upstream or catalog-sources config, then rerun scripts/import_external_catalog_sources.py. -->
 # .NET MAUI Doctor
 
 Validate and fix .NET MAUI development environments. All version requirements are discovered dynamically from NuGet APIs — never hardcode versions.

catalog/Frameworks/Official-DotNet-MAUI/skills/maui-app-lifecycle/SKILL.md

@@ -3,8 +3,6 @@ name: maui-app-lifecycle
 description: ".NET MAUI app lifecycle guidance — the four app states, cross-platform Window lifecycle events (Created, Activated, Deactivated, Stopped, Resumed, Destroying), platform-specific lifecycle mapping, backgrounding and resume behavior, and state-preservation patterns. USE FOR: \"app lifecycle\", \"window lifecycle events\", \"save state on background\", \"resume app\", \"OnStopped\", \"OnResumed\", \"backgrounding\", \"deactivated event\", \"ConfigureLifecycleEvents\", \"platform lifecycle hooks\". DO NOT USE FOR: navigation events (use maui-shell-navigation), dependency injection setup (use maui-dependency-injection), platform API invocation (use conditional compilation and partial classes)."
 compatibility: "Requires a .NET MAUI project or solution."
 ---
-
-<!-- Imported from upstreams/dotnet-skills/dotnet-maui/skills/maui-app-lifecycle/SKILL.md via vendir. Edit upstream or catalog-sources config, then rerun scripts/import_external_catalog_sources.py. -->
 # .NET MAUI App Lifecycle
 
 Handle application state transitions correctly in .NET MAUI. This skill covers the cross-platform Window lifecycle events, their platform-native mappings, and patterns for preserving state across backgrounding and resume cycles.

catalog/Frameworks/Official-DotNet-MAUI/skills/maui-collectionview/SKILL.md

@@ -3,8 +3,6 @@ name: maui-collectionview
 description: "Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: \"CollectionView\", \"list view\", \"grid layout\", \"data template\", \"item template\", \"grouping\", \"pull to refresh\", \"incremental loading\", \"swipe actions\", \"empty view\", \"selection mode\", \"scroll to item\", displaying scrollable data, replacing ListView. DO NOT USE FOR: simple static layouts without scrollable data (use Grid or StackLayout), map pin lists (use Microsoft.Maui.Controls.Maps), table-based data entry forms, or non-MAUI list controls."
 compatibility: "Requires a .NET MAUI project or solution."
 ---
-
-<!-- Imported from upstreams/dotnet-skills/dotnet-maui/skills/maui-collectionview/SKILL.md via vendir. Edit upstream or catalog-sources config, then rerun scripts/import_external_catalog_sources.py. -->
 # CollectionView — .NET MAUI
 
 `CollectionView` is the primary control for displaying scrollable lists and grids of data in .NET MAUI. It replaces `ListView` with better performance, flexible layouts, and no `ViewCell` requirement.