From ae251baff6da7e96c01c7e004cc84feec31d7ab0 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 6 Sep 2026 16:09:57 +0200 Subject: [PATCH 1/4] docs: simplify plugin onboarding and link the full catalogue --- AGENTS.md | 21 +-- README.md | 198 ++--------------------------- docs/installation.md | 65 ++++++++++ docs/plugins.md | 16 +++ docs/resources.md | 107 ++++++++++++++++ scripts/validate-manifests.sh | 16 ++- scripts/validate-manifests.test.sh | 45 ++++--- 7 files changed, 247 insertions(+), 221 deletions(-) create mode 100644 docs/installation.md create mode 100644 docs/plugins.md create mode 100644 docs/resources.md diff --git a/AGENTS.md b/AGENTS.md index 81029b51..1e777946 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,7 +38,7 @@ plugins/ │ └── /SKILL.md # An installed skill copied from upstream, with metadata.github-* provenance └── resources/ # Optional ancillary, explicitly linked human-consumed assets scripts/ -├── validate-manifests.sh # Manifest + parity + plugin.json + README-table + skill-provenance guard (single source of truth; run locally before pushing) +├── validate-manifests.sh # Manifest + parity + plugin.json + catalogue-table + skill-provenance guard (single source of truth; run locally before pushing) ├── validate-manifests.test.sh # Self-test: PASS a consistent fixture, FAIL each drift scenario the guard catches ├── check-plugin-version-bump.sh # Gate: a plugin whose shipped content changed must move its version ├── check-plugin-version-bump.test.sh # Self-test for the gate above @@ -51,11 +51,14 @@ scripts/ ├── refresh-desired-state-digests.sh # Writer: recompute every digest a *.desired-state.json pins (the fix "digest must match" points at) ├── refresh-desired-state-digests.test.sh # Self-test for the generator, incl. its coupling to the validator └── sha256.lib.sh # The two hashing rules, sourced by BOTH the validator and the generator so they cannot drift -README.md # Human-facing index — the plugin table + per-tool install instructions +README.md # Short introduction and getting started +docs/plugins.md # Validated plugin catalogue and resource inventory +docs/installation.md # Per-tool installation instructions +docs/resources.md # Bundled servers, agents, and onboarding ``` -See [README.md](README.md) for the plugin catalogue and the per-tool -[Installation](README.md#installation) instructions. +See the [plugin catalogue](docs/plugins.md) and the per-tool +[installation instructions](docs/installation.md). ## The two marketplace manifests are the contract @@ -71,7 +74,7 @@ same `name`/`description`/`version` and `source` `./plugins/`) plus an equ requires the canonical nested path in strict mode even though the local Claude CLI and Copilot accept the top-level manifest; CI normalises and compares both copies so they cannot drift. No `plugins//` may exist without a manifest entry. CI also -checks the human-facing **README plugin table** against the filesystem: every plugin has a table row +checks the human-facing **plugin catalogue table** against the filesystem: every plugin has a table row (and vice versa) and each row's **Resources** column matches that plugin's bundled resources — its on-disk `skills/` directories, any MCP server keys in an optional `plugins//.mcp.json`, and any custom-agent entries in an optional `plugins//agents/` — so the catalogue a reader sees can never @@ -86,7 +89,7 @@ missing persisted entries, active names used as rename sources, dangling targets chain must end at a current plugin name or `null` for an intentional removal. Ancillary desired-state documents under `plugins//resources/*.desired-state.json` are not -auto-discovered plugin components and therefore are not counted in the README Resources column. CI +auto-discovered plugin components and therefore are not counted in the catalogue Resources column. CI validates their provider-neutral schema, required consumer contract, lack of placeholders, and explicit link from the owning plugin README. Agentic-engineering desired state must include the complete set of thin schedule prompts validated by the script; schedule prompts point to canonical role sources and do @@ -104,7 +107,7 @@ a hermetic `*.test.sh` next to it that stubs any external tool on `PATH` (no net asserts the script's contract. The `lint-scripts` CI job auto-discovers both locations — shellcheck over every script, then every `*.test.sh` — so a new script and its test are picked up without editing the workflow. A `scripts/` directory is a helper location, not an auto-discovered plugin resource: it -never satisfies the minimum-one-resource rule and is not listed in the README Resources column. +never satisfies the minimum-one-resource rule and is not listed in the catalogue Resources column. Each entry's `source` is a **relative path** (`./plugins/`), so the repo rename (`copilot-plugins` → `agent-plugins`, see [#7](https://github.com/devantler-tech/agent-plugins/issues/7)) and any @@ -192,7 +195,7 @@ plugin membership) is authored here. version must agree (the portable and strict manifests plus both marketplace entries) — a hand-edit easily half-lands. The `Check version bump` CI job enforces it on every PR, and the daily skill-sync workflow bumps itself via `--changed-since` so the automated update PR satisfies the gate unaided. -9. **README and manifests stay in lockstep.** The README plugin table mirrors the manifests; update it +9. **Catalogue and manifests stay in lockstep.** The [plugin catalogue table](docs/plugins.md) mirrors the manifests; update it in the same PR whenever the plugin set changes. CI enforces this: every plugin has a table row and vice versa, and each row's **Resources** column matches that plugin's bundled resources on disk — its `skills/` directories, any `.mcp.json` server keys, and any `agents/` entries (the **Description** @@ -210,7 +213,7 @@ runs once after installation and remains required. `scripts/install-skills-ref.t recovery and failure offline in `lint-scripts`. ```bash -# 1. Marketplace parity, portable ↔ strict-Claude plugin.json parity, README table, +# 1. Marketplace parity, portable ↔ strict-Claude plugin.json parity, catalogue table, # desired-state resources, and skill provenance — the exact checks CI's # "Validate manifests" job runs. ./scripts/validate-manifests.sh diff --git a/README.md b/README.md index ad2612df..3600a777 100644 --- a/README.md +++ b/README.md @@ -1,200 +1,26 @@ -# devantler-tech/agent-plugins +# Agent Plugins -A tool-neutral [agent-plugin marketplace](https://code.visualstudio.com/docs/copilot/customization/agent-plugins) that bundles curated agent skills — sourced from across the agent-skill ecosystem — into category-based plugins. +Ready-to-install bundles that teach your AI coding assistant new skills, connect it to tools, and give it specialist roles. For developers using **VS Code**, **GitHub Copilot CLI**, or **Claude Code**. -Supports **VS Code**, **GitHub Copilot CLI**, and **Claude Code** via dual marketplace manifests. +## Start here -## Scope - -This is a **tool-neutral plugin marketplace**, not a skills-only bundler. Every plugin published today bundles [agent skills](https://github.com/devantler-tech/agent-skills), but a plugin may bundle **any agent resource** — skills, [MCP](https://modelcontextprotocol.io) servers, and custom agents — so the marketplace can grow with the cross-tool agent ecosystem instead of being pinned to one tool or one resource type. Additional resource types are added as they prove out across the supported tools. - -## Plugins - -| Plugin | Resources | Description | -|--------|-----------|-------------| -| [`gitops-kubernetes`](plugins/gitops-kubernetes/) | `gitops-cluster-debug`, `gitops-knowledge`, `gitops-tenant-onboarding` (skills) · `flux-operator-mcp` (MCP server) · `flux-troubleshooter` (agent) | Flux CD debugging, knowledge, and tenant onboarding — bundles the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging | -| [`github`](plugins/github/) | `gh-cli`, `gh-stack`, `github-actions-docs`, `github-issues` | GitHub CLI, stacked PRs, Actions docs, and issue management | -| [`agentic-engineering`](plugins/agentic-engineering/) | `agent-improvement`, `agent-instructions`, `find-skills`, `portfolio-maintenance`, `product-engineering`, `self-improvement` (skills) · `agent-improver`, `agentic-engineer`, `portfolio-surveyor` (agents) | The autonomous engineering system for a whole repository portfolio — engineer, read-only surveyor, and meta-engineer agents plus their operating, spend, and improvement workflows; configured by the consumer's `AGENTS.md` | -| [`go`](plugins/go/) | `golang-pro` | Go best practices, concurrency, generics, interfaces, and testing | -| [`engineering-practices`](plugins/engineering-practices/) | `conventional-release`, `git-commit`, `refactor`, `test-driven-development`, `ways-of-working` | Git commits, conventional releases, refactoring, TDD, and engineering ways of working | -| [`frontend-design`](plugins/frontend-design/) | `astro`, `frontend-design`, `web-design-guidelines` | Astro, frontend design, and web design guidelines | -| [`vibe-coding`](plugins/vibe-coding/) | `needs-stack-mapping`, `allowed-stack-guardrail`, `jargon-free-voice` (skills) · `vibe-coding-companion` (agent) | Build a product by conversation alone — plain-language companion agent + guardrailed needs-to-stack skills for people with no technical background | - -## Installation - -### VS Code - -Add the marketplace to your settings: - -```jsonc -// settings.json -"chat.plugins.marketplaces": [ - "devantler-tech/agent-plugins" -] -``` - -Then browse **Extensions → Agent Plugins** (`@agentPlugins` search) to install individual plugins. - -### Copilot CLI - -```sh -# Browse available plugins -copilot plugin marketplace browse devantler-tech/agent-plugins - -# Install a plugin -copilot plugin install gitops-kubernetes@devantler-plugins -``` - -### Claude Code - -Add the marketplace, then install a plugin — run these inside Claude Code: +In **Claude Code**, add the marketplace and install the GitHub tools bundle: ```text /plugin marketplace add devantler-tech/agent-plugins -/plugin install gitops-kubernetes@devantler-plugins +/plugin install github@devantler-plugins ``` -Browse everything on offer with `/plugin` (**Discover** tab) or list it with `/plugin list`. The bundled [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) is also discovered automatically when this repo is added as a plugin source. - -Claude Desktop can add the same GitHub repository from **Plugins → Personal**. That path validates the marketplace remotely in strict mode; every plugin therefore includes the canonical `.claude-plugin/plugin.json` manifest it requires. - -### Any other agent — skills only, via `npx skills` - -[`npx skills`](https://github.com/vercel-labs/skills) reads this repo's [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and installs the bundled **skills** into any of its 70+ supported agents — useful when your agent isn't one of the three above: - -```sh -# Browse the bundled skills without installing -npx skills add devantler-tech/agent-plugins --list - -# Install specific skills for a specific agent -npx skills add devantler-tech/agent-plugins --skill gitops-knowledge --agent cursor -``` - -> [!IMPORTANT] -> This is a **partial** install path. The example installs only `gitops-knowledge` for Cursor. Use -> `--all` to install every bundled skill across detected agents, or combine a pattern such as -> `--skill gitops-*` with `--agent cursor` to target that agent. None of these skills-only forms -> install the [MCP servers](#mcp-servers) or [custom agents](#custom-agents). To get everything a -> plugin bundles, install it as a plugin in **VS Code**, **Copilot CLI**, or **Claude Code** above — -> all three load a plugin's bundled `.mcp.json` and `agents/` automatically. - -## Copy-paste agent onboarding - -The [`agentic-engineering` desired-state manifest](plugins/agentic-engineering/resources/provider-neutral.desired-state.json) -is a provider-neutral, copy-paste onboarding document for a new assistant. Open the assistant in the -consumer repository, paste the complete JSON, and ask it to reconcile the desired state. It points to -the latest reviewed plugin for generic role logic and to the consumer's `AGENTS.md` for organization, -trust, cadence, memory, and maintainer-channel configuration. It also requires the assistant to report -unsupported native capabilities instead of silently weakening the deployment. The manifest carries -separate thin schedule prompts for the Agentic Engineer and the Agent Improver; each resolves its -cadence and deployment facts from the canonical consumer instructions. Spend stewardship has no -schedule of its own — it runs inside the engineer's loop when the consumer declares a `Spend contract` -section. -Existing installations must complete **all three** migrations, in order, before their next scheduled -run — the -[version 2 checklist](plugins/agentic-engineering/README.md#migrating-from-automated-ai-engineer) -(plugin identity), **then** the -[version 3 checklist](plugins/agentic-engineering/README.md#migrating-to-version-3) (retire the -`finops-engineer` schedule and adopt the `Spend contract` section), **then** the -[version 4 checklist](plugins/agentic-engineering/README.md#migrating-to-the-agentic-engineer-entrypoint) -(the `automated-ai-engineer` → `agentic-engineer` entrypoint rename). Stopping early would resume -unattended writes with the retired FinOps schedule still armed, or with a schedule pointing at an -entrypoint that no longer resolves. - -## MCP servers - -A plugin may bundle [MCP](https://modelcontextprotocol.io) servers as well as skills. The -[`gitops-kubernetes`](plugins/gitops-kubernetes/) plugin bundles the **Flux MCP server** -([`flux-operator-mcp`](https://github.com/controlplaneio-fluxcd/flux-operator/tree/main/cmd/mcp)) -so its `gitops-cluster-debug` skill — which `Requires flux-operator-mcp` — works against a live -cluster out of the box. - -The server is authored once as the plugin's [`.mcp.json`](plugins/gitops-kubernetes/.mcp.json) -(`mcpServers` map). How each tool consumes it differs (per [ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)): - -- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `.mcp.json` is loaded automatically - when the plugin is installed; no extra configuration is needed. In VS Code the server starts and - stops with the plugin and needs no separate trust prompt, because installing the plugin is what - grants the trust. - -You only need to write MCP config by hand if you are **not** installing this as a plugin — then add the -server to your workspace `.vscode/mcp.json` (note the key there is `servers`, not `mcpServers`): - -```json -{ - "servers": { - "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve"] } - } -} -``` - -Every path invokes the same `flux-operator-mcp` binary, so install it first — e.g. -`brew install controlplaneio-fluxcd/tap/flux-operator-mcp` or `go install -github.com/controlplaneio-fluxcd/flux-operator/cmd/mcp@latest` (it reads your kubeconfig from -`KUBECONFIG` / `~/.kube/config`). See the -[Flux MCP docs](https://fluxcd.control-plane.io/operator/mcp/) for read-only mode and remote -transport. - -## Custom agents - -A plugin may also bundle **custom agents** (subagents). The -[`gitops-kubernetes`](plugins/gitops-kubernetes/) plugin bundles -[`flux-troubleshooter`](plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md) — a **read-only** -Flux CD triage agent that traces the GitOps dependency chain (source → Kustomization/HelmRelease → -workloads), reads status conditions and controller logs via the bundled `flux-operator-mcp` server, -and returns a root-cause diagnosis plus the human-applied fix. It has no apply/reconcile/suspend/ -delete tool by design, so it never mutates the cluster. - -The agent is authored once as `agents/.agent.md` (Markdown + YAML frontmatter, with the neutral -`name`/`description`/`tools`/`model` core). The `.agent.md` filename is what VS Code and Copilot -discover inside a plugin's `agents/` directory; Claude Code is filename-agnostic (it reads any -Markdown in `agents/` and takes the agent's name from frontmatter), so one file serves all three -tools. The same goes for the `tools:` allowlist: MCP tools are listed in both spellings — Claude -Code's `mcp____` and VS Code / Copilot's `/` — because each tool -ignores entries it does not recognise (per -[ADR 0001](docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)): - -- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded - automatically when the plugin is installed; in Claude Code the agent is namespaced - `gitops-kubernetes:flux-troubleshooter`. - -As with MCP, hand-placing an agent at `.github/agents/.agent.md` is only for setups that aren't -installing this as a plugin. - -The [`vibe-coding`](plugins/vibe-coding/) plugin bundles -[`vibe-coding-companion`](plugins/vibe-coding/agents/vibe-coding-companion.agent.md) — a plain-language -build companion for a non-technical audience (design: -[ADR 0003](docs/adr/0003-vibe-coding-plugin-design.md)). Same delivery rules. Its guardrail requires -the consuming deployment to author a `## Stack map` section in its `AGENTS.md` (see the -[plugin README](plugins/vibe-coding/README.md)). - -The [`agentic-engineering`](plugins/agentic-engineering/) plugin bundles three agents — -[`agentic-engineer`](plugins/agentic-engineering/agents/agentic-engineer.agent.md) (the -autonomous portfolio-engineer actor), -[`portfolio-surveyor`](plugins/agentic-engineering/agents/portfolio-surveyor.agent.md) (its read-only -survey subagent), and -[`agent-improver`](plugins/agentic-engineering/agents/agent-improver.agent.md) (a meta-engineer that -improves the engineer itself from measured evidence) — alongside its engineering skills (design: -[ADR 0002](docs/adr/0002-automated-ai-engineer-plugin-boundary.md), consolidation: -[ADR 0004](docs/adr/0004-consolidate-agentic-engineering.md), spend stewardship: -[ADR 0005](docs/adr/0005-merge-spend-stewardship-into-the-engineer.md)). Same delivery rules; the -consuming deployment must define the five contract sections (Portfolio map, Trust gate, Cadence, -Memory, Maintainer channels) in its `AGENTS.md` — plus **Agent definition locations** and -**Authority model** if it enables `agent-improver`, and **Spend contract** if it wants the engineer to -steward spend (see the [plugin README](plugins/agentic-engineering/README.md)). - -## How it works - -Skills are installed from their upstream repositories using [`gh skill install`](https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/). A [daily update workflow](.github/workflows/update-agent-skills.yaml) runs [`gh skill update --all`](https://github.com/devantler-tech/actions/tree/main/update-agent-skills) via the [`update-agent-skills`](https://github.com/devantler-tech/actions/blob/main/.github/workflows/update-agent-skills.yaml) reusable workflow and opens a PR when upstream content has drifted. +Using another tool? Follow the [VS Code](docs/installation.md#vs-code), [Copilot CLI](docs/installation.md#copilot-cli), [Claude Desktop](docs/installation.md#claude-code), or [skills-only installation guide](docs/installation.md#any-other-agent--skills-only-via-npx-skills). -Each plugin directory is self-contained with a portable top-level `plugin.json` manifest, a semantically identical `.claude-plugin/plugin.json` for strict Claude remote ingestion, and its bundled resources — a `skills/` subdirectory holding the installed `SKILL.md` files (plus any supporting assets), and optionally an `.mcp.json` declaring bundled MCP servers and an `agents/` directory holding custom agents. CI rejects a missing, malformed, or divergent manifest copy. A plugin may also carry ancillary, human-consumed assets under `resources/`, such as a desired-state document; these are linked explicitly rather than treated as auto-discovered runtime components. Each `SKILL.md` contains `metadata.github-*` frontmatter for upstream provenance — no lockfile needed. +## Choose a bundle -Each bundled skill is pulled from its own upstream (recorded in its `SKILL.md` `metadata.github-*` frontmatter), spanning many sources — including our in-house sibling library [`devantler-tech/agent-skills`](https://github.com/devantler-tech/agent-skills). +Browse the [full plugin catalogue](docs/plugins.md) for GitHub workflows, Kubernetes operations, Go development, frontend design, engineering practices, autonomous engineering, and building by conversation. -## Contributing +The [autonomous engineering setup](plugins/agentic-engineering/README.md) explains how to configure the engineer, surveyor, and improver for your repositories. The [server and agent guide](docs/resources.md) covers bundled connections, prerequisites, and specialist roles. -See the [devantler-tech organisation guidelines](https://github.com/devantler-tech/.github) for PR/issue templates and contribution rules. +## Contribute -## License +Skills come from their original authors, including [Agent Skills](https://github.com/devantler-tech/agent-skills). To suggest a bundle or report a problem, [open an issue](https://github.com/devantler-tech/agent-plugins/issues). For repository changes, read the [contributor instructions](AGENTS.md). -Apache 2.0 — see [`LICENSE`](LICENSE). +[Apache 2.0 license](LICENSE) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..2170fded --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,65 @@ +# Installation + +### VS Code + +Add the marketplace to your settings: + +```jsonc +// settings.json +"chat.plugins.marketplaces": [ + "devantler-tech/agent-plugins" +] +``` + +Then open **Extensions**, search `@agentPlugins`, and install a plugin from this marketplace. Review the source when VS Code asks you to trust it. See the [VS Code plugin guide](https://code.visualstudio.com/docs/agent-customization/agent-plugins). + +### Copilot CLI + +Run these in your terminal; `devantler-plugins` is the marketplace name registered by the first command. See the [Copilot plugin reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference). + +```sh +# Register the marketplace +copilot plugin marketplace add devantler-tech/agent-plugins + +# Browse available plugins +copilot plugin marketplace browse devantler-plugins + +# Install a plugin +copilot plugin install gitops-kubernetes@devantler-plugins +``` + +### Claude Code + +Add the marketplace, then install a plugin — run these inside Claude Code ([official guide](https://code.claude.com/docs/en/discover-plugins)): + +```text +/plugin marketplace add devantler-tech/agent-plugins +/plugin install gitops-kubernetes@devantler-plugins +``` + +Browse everything on offer with `/plugin` (**Discover** tab) or list it with `/plugin list`. The bundled [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) is also discovered automatically when this repo is added as a plugin source. + +Claude Desktop can add the same GitHub repository from **Plugins → Personal**. That path validates the marketplace remotely in strict mode; every plugin therefore includes the canonical `.claude-plugin/plugin.json` manifest it requires. + +### Any other agent — skills only, via `npx skills` + +[`npx skills`](https://github.com/vercel-labs/skills) reads this repo's [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) and installs the bundled **skills** into any of its 70+ supported agents — useful when your agent isn't one of the three above: + +```sh +# Browse the bundled skills without installing +npx skills add devantler-tech/agent-plugins --list + +# Install specific skills for a specific agent +npx skills add devantler-tech/agent-plugins --skill gitops-knowledge --agent cursor +``` + +> [!IMPORTANT] +> This is a **partial** install path. The example installs only `gitops-knowledge` for Cursor. Use +> `--all` to install every bundled skill across detected agents, or combine a pattern such as +> `--skill gitops-*` with `--agent cursor` to target that agent. None of these skills-only forms +> install the [MCP servers](resources.md#mcp-servers) or [custom agents](resources.md#custom-agents). To get everything a +> plugin bundles, install it as a plugin in **VS Code**, **Copilot CLI**, or **Claude Code** above — +> all three load a plugin's bundled `.mcp.json` and `agents/` automatically. + + +[Plugin catalogue](plugins.md) · [Bundled servers and agents](resources.md) diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000..9694036e --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,16 @@ +# Plugin catalogue + +A **skill** teaches an assistant a task. An **agent** gives it a specialized role; an **MCP server** connects it to external tools through the Model Context Protocol. + +[Install a plugin](installation.md) · [Back to the overview](../README.md) + +| Plugin | Resources | Description | +|--------|-----------|-------------| +| [`gitops-kubernetes`](../plugins/gitops-kubernetes/) | `gitops-cluster-debug`, `gitops-knowledge`, `gitops-tenant-onboarding` (skills) · `flux-operator-mcp` (MCP server) · `flux-troubleshooter` (agent) | Flux CD debugging, knowledge, and tenant onboarding — bundles the Flux MCP server and a read-only Flux troubleshooter agent for live-cluster debugging | +| [`github`](../plugins/github/) | `gh-cli`, `gh-stack`, `github-actions-docs`, `github-issues` | GitHub CLI, stacked PRs, Actions docs, and issue management | +| [`agentic-engineering`](../plugins/agentic-engineering/) | `agent-improvement`, `agent-instructions`, `find-skills`, `portfolio-maintenance`, `product-engineering`, `self-improvement` (skills) · `agent-improver`, `agentic-engineer`, `portfolio-surveyor` (agents) | The autonomous engineering system for a whole repository portfolio — engineer, read-only surveyor, and meta-engineer agents plus their operating, spend, and improvement workflows; configured by the consumer's `AGENTS.md` | +| [`go`](../plugins/go/) | `golang-pro` | Go best practices, concurrency, generics, interfaces, and testing | +| [`engineering-practices`](../plugins/engineering-practices/) | `conventional-release`, `git-commit`, `refactor`, `test-driven-development`, `ways-of-working` | Git commits, conventional releases, refactoring, TDD, and engineering ways of working | +| [`frontend-design`](../plugins/frontend-design/) | `astro`, `frontend-design`, `web-design-guidelines` | Astro, frontend design, and web design guidelines | +| [`vibe-coding`](../plugins/vibe-coding/) | `needs-stack-mapping`, `allowed-stack-guardrail`, `jargon-free-voice` (skills) · `vibe-coding-companion` (agent) | Build a product by conversation alone — plain-language companion agent + guardrailed needs-to-stack skills for people with no technical background | + diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 00000000..c8e6265c --- /dev/null +++ b/docs/resources.md @@ -0,0 +1,107 @@ +# Bundled servers and agents + +[Plugin catalogue](plugins.md) · [Installation](installation.md) + +## Copy-paste agent onboarding + +The [`agentic-engineering` desired-state manifest](../plugins/agentic-engineering/resources/provider-neutral.desired-state.json) +is a provider-neutral, copy-paste onboarding document for a new assistant. Open the assistant in the +consumer repository, paste the complete JSON, and ask it to reconcile the desired state. It points to +the latest reviewed plugin for generic role logic and to the consumer's `AGENTS.md` for organization, +trust, cadence, memory, and maintainer-channel configuration. It also requires the assistant to report +unsupported native capabilities instead of silently weakening the deployment. The manifest carries +separate thin schedule prompts for the Agentic Engineer and the Agent Improver; each resolves its +cadence and deployment facts from the canonical consumer instructions. Spend stewardship has no +schedule of its own — it runs inside the engineer's loop when the consumer declares a `Spend contract` +section. +Existing installations must complete **all three** migrations, in order, before their next scheduled +run — the +[version 2 checklist](../plugins/agentic-engineering/README.md#migrating-from-automated-ai-engineer) +(plugin identity), **then** the +[version 3 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-3) (retire the +`finops-engineer` schedule and adopt the `Spend contract` section), **then** the +[version 4 checklist](../plugins/agentic-engineering/README.md#migrating-to-the-agentic-engineer-entrypoint) +(the `automated-ai-engineer` → `agentic-engineer` entrypoint rename). Stopping early would resume +unattended writes with the retired FinOps schedule still armed, or with a schedule pointing at an +entrypoint that no longer resolves. + +## MCP servers + +A plugin may bundle [MCP](https://modelcontextprotocol.io) servers as well as skills. The +[`gitops-kubernetes`](../plugins/gitops-kubernetes/) plugin bundles the **Flux MCP server** +([`flux-operator-mcp`](https://github.com/controlplaneio-fluxcd/flux-operator/tree/main/cmd/mcp)) +so its `gitops-cluster-debug` skill — which `Requires flux-operator-mcp` — can connect to a live cluster once the server binary and cluster access are configured. + +The server is authored once as the plugin's [`.mcp.json`](../plugins/gitops-kubernetes/.mcp.json) +(`mcpServers` map). How each tool consumes it differs (per [ADR 0001](../docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)): + +- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `.mcp.json` is loaded automatically + when the plugin is installed. The server binary must be installed separately and have access to + the intended cluster. + +You only need to write MCP config by hand if you are **not** installing this as a plugin — then add the +server to your workspace `.vscode/mcp.json` (note the key there is `servers`, not `mcpServers`): + +```json +{ + "servers": { + "flux-operator-mcp": { "command": "flux-operator-mcp", "args": ["serve"] } + } +} +``` + +Every path invokes the same `flux-operator-mcp` binary, so install it first — e.g. +`brew install controlplaneio-fluxcd/tap/flux-operator-mcp` or `go install +github.com/controlplaneio-fluxcd/flux-operator/cmd/mcp@latest` (it reads your kubeconfig from +`KUBECONFIG` / `~/.kube/config`). See the +[Flux MCP docs](https://fluxcd.control-plane.io/operator/mcp/) for read-only mode and remote +transport. + +## Custom agents + +A plugin may also bundle **custom agents** (subagents). The +[`gitops-kubernetes`](../plugins/gitops-kubernetes/) plugin bundles +[`flux-troubleshooter`](../plugins/gitops-kubernetes/agents/flux-troubleshooter.agent.md) — a **read-only** +Flux CD triage agent that traces the GitOps dependency chain (source → Kustomization/HelmRelease → +workloads), reads status conditions and controller logs via the bundled `flux-operator-mcp` server, +and returns a root-cause diagnosis plus the human-applied fix. It has no apply/reconcile/suspend/ +delete tool by design, so it never mutates the cluster. + +The agent is authored once as `agents/.agent.md` (Markdown + YAML frontmatter, with the neutral +`name`/`description`/`tools`/`model` core). The `.agent.md` filename is what VS Code and Copilot +discover inside a plugin's `agents/` directory; Claude Code is filename-agnostic (it reads any +Markdown in `agents/` and takes the agent's name from frontmatter), so one file serves all three +tools. The same goes for the `tools:` allowlist: MCP tools are listed in both spellings — Claude +Code's `mcp____` and VS Code / Copilot's `/` — because each tool +ignores entries it does not recognise (per +[ADR 0001](../docs/adr/0001-bundling-mcp-servers-and-custom-agents.md)): + +- **Claude Code**, **Copilot CLI**, and **VS Code** — the bundled `agents/` directory is loaded + automatically when the plugin is installed; in Claude Code the agent is namespaced + `gitops-kubernetes:flux-troubleshooter`. + +As with MCP, hand-placing an agent at `.github/agents/.agent.md` is only for setups that aren't +installing this as a plugin. + +The [`vibe-coding`](../plugins/vibe-coding/) plugin bundles +[`vibe-coding-companion`](../plugins/vibe-coding/agents/vibe-coding-companion.agent.md) — a plain-language +build companion for a non-technical audience (design: +[ADR 0003](../docs/adr/0003-vibe-coding-plugin-design.md)). Same delivery rules. Its guardrail requires +the consuming deployment to author a `## Stack map` section in its `AGENTS.md` (see the +[plugin README](../plugins/vibe-coding/README.md)). + +The [`agentic-engineering`](../plugins/agentic-engineering/) plugin bundles three agents — +[`agentic-engineer`](../plugins/agentic-engineering/agents/agentic-engineer.agent.md) (the +autonomous portfolio-engineer actor), +[`portfolio-surveyor`](../plugins/agentic-engineering/agents/portfolio-surveyor.agent.md) (its read-only +survey subagent), and +[`agent-improver`](../plugins/agentic-engineering/agents/agent-improver.agent.md) (a meta-engineer that +improves the engineer itself from measured evidence) — alongside its engineering skills (design: +[ADR 0002](../docs/adr/0002-automated-ai-engineer-plugin-boundary.md), consolidation: +[ADR 0004](../docs/adr/0004-consolidate-agentic-engineering.md), spend stewardship: +[ADR 0005](../docs/adr/0005-merge-spend-stewardship-into-the-engineer.md)). Same delivery rules; the +consuming deployment must define the five contract sections (Portfolio map, Trust gate, Cadence, +Memory, Maintainer channels) in its `AGENTS.md` — plus **Agent definition locations** and +**Authority model** if it enables `agent-improver`, and **Spend contract** if it wants the engineer to +steward spend (see the [plugin README](../plugins/agentic-engineering/README.md)). + diff --git a/scripts/validate-manifests.sh b/scripts/validate-manifests.sh index 8fbdad06..92351e3e 100755 --- a/scripts/validate-manifests.sh +++ b/scripts/validate-manifests.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Validate the plugin marketplace manifests, every plugins//plugin.json, and the -# README plugin table. +# plugin catalogue table. # # Single source of truth for the checks the 🧪 CI "Validate manifests" job runs: # 1. Both marketplace manifests (Copilot + Claude) are well-formed (.name + .plugins). @@ -10,7 +10,7 @@ # equivalent .claude-plugin/plugin.json for strict Claude ingestion. # 5. Manifest entries and on-disk plugins are in lockstep (no missing/orphan plugin, # no name/description/version/source divergence). -# 6. The README plugin table and on-disk plugin resources are in lockstep (every plugin +# 6. The plugin catalogue table and on-disk plugin resources are in lockstep (every plugin # has a row and vice versa; each row's Resources column matches the plugin's bundled # skills + MCP servers). # 7. Ancillary *.desired-state.json onboarding resources are structurally complete, @@ -26,7 +26,7 @@ set -euo pipefail COPILOT_MANIFEST=".github/plugin/marketplace.json" CLAUDE_MANIFEST=".claude-plugin/marketplace.json" RENAME_HISTORY="scripts/marketplace-rename-history.json" -README="README.md" +README="docs/plugins.md" # Digest helpers are shared with the desired-state digest generator, so the value this # gate demands and the value that generator writes cannot drift apart. See @@ -377,7 +377,7 @@ plugin_disk_resources() { } | sort | tr '\n' ' ' } -# 6. The README plugin table and on-disk plugin resources are in lockstep. +# 6. The plugin catalogue table and on-disk plugin resources are in lockstep. # Table rows look like: # | [``](plugins//) | `skill-a`, `mcp-server-b` | | # The Resources column lists every bundled skill AND MCP server; the Description @@ -386,10 +386,14 @@ plugin_disk_resources() { # substitution — SC2016 (won't-expand) is a false positive here. # shellcheck disable=SC2016 validate_readme_parity() { + if [ ! -f "$README" ]; then + echo "::error::$README: plugin catalogue is missing" + return 1 + fi local failed=0 local line name readme_resources disk_resources local readme_names=() - # Each README plugin row: parse the plugin name (col 1) and its Resources column (col 3). + # Each catalogue row: parse the plugin name (col 1) and its Resources column (col 3). while IFS= read -r line; do name=$(printf '%s' "$line" | sed -nE 's/^\| \[`([a-z0-9-]+)`\].*/\1/p') [ -z "$name" ] && continue @@ -412,7 +416,7 @@ validate_readme_parity() { echo "✓ $README ↔ plugins/$name (resources: ${disk_resources% })" fi done < <(grep -E '^\| \[`[a-z0-9-]+`\]' "$README") - # Every plugins// on disk appears as a README row (no plugin missing from the table). + # Every plugins// on disk appears as a catalogue row (no plugin missing from the table). local pj listed rn for pj in plugins/*/plugin.json; do name=$(jq -r '.name' "$pj") diff --git a/scripts/validate-manifests.test.sh b/scripts/validate-manifests.test.sh index 80012651..1e2c82e1 100755 --- a/scripts/validate-manifests.test.sh +++ b/scripts/validate-manifests.test.sh @@ -52,7 +52,7 @@ sync_entrypoint_digest() { # Build a complete, valid fixture repo (two plugins) at $1. make_fixture() { local root="$1" - mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" + mkdir -p "$root/.github/plugin" "$root/.claude-plugin" "$root/scripts" "$root/docs" local manifest='{ "name": "devantler-plugins", "renames": { @@ -71,7 +71,7 @@ make_fixture() { make_plugin "$root" alpha "Alpha plugin" "1.0.0" make_plugin "$root" beta "Beta plugin" "1.0.0" # A README plugin table in lockstep with the two plugins + their example-skill. - cat > "$root/README.md" <<'EOF' + cat > "$root/docs/plugins.md" <<'EOF' # fixture | Plugin | Skills | Description | @@ -358,13 +358,18 @@ check_fail "plugin.json name drift vs manifest fails" "name does not match manif d=$(fresh); make_plugin "$d" gamma "Orphan plugin" "1.0.0" check_fail "orphan plugin not in manifest fails" "plugins/gamma is not listed in" "$d" -# --- check 5: README plugin table <-> plugins/skills lockstep --- +# --- check 5: catalogue table <-> plugins/skills lockstep --- +d=$(fresh) +cp "$d/docs/plugins.md" "$d/README.md" +rm "$d/docs/plugins.md" +check_fail "a stale README cannot replace the missing catalogue" "docs/plugins.md: plugin catalogue is missing" "$d" + # A README row for a plugin that does not exist on disk. # (literal backticks in the table cell, not command substitution — SC2016 false positive) d=$(fresh) # shellcheck disable=SC2016 -printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/README.md" -check_fail "README row for nonexistent plugin fails" "README.md lists plugin 'gamma' with no plugins/gamma/plugin.json on disk" "$d" +printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/docs/plugins.md" +check_fail "README row for nonexistent plugin fails" "docs/plugins.md lists plugin 'gamma' with no plugins/gamma/plugin.json on disk" "$d" # A README row whose plugins// exists but has no plugin.json (a stray dir the # orphan scan can't see) must be rejected, not silently accepted. @@ -372,26 +377,26 @@ d=$(fresh) mkdir -p "$d/plugins/gamma/skills/example-skill" printf 'Ghost skill.\n' > "$d/plugins/gamma/skills/example-skill/SKILL.md" # shellcheck disable=SC2016 -printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/README.md" -check_fail "README row for dir without plugin.json fails" "README.md lists plugin 'gamma' with no plugins/gamma/plugin.json on disk" "$d" +printf '| [`gamma`](plugins/gamma/) | `example-skill` | Ghost plugin |\n' >> "$d/docs/plugins.md" +check_fail "README row for dir without plugin.json fails" "docs/plugins.md lists plugin 'gamma' with no plugins/gamma/plugin.json on disk" "$d" # A stray skill directory with no SKILL.md is still counted, so the README Resources # column drifts out of lockstep and the guard fails (it is not silently hidden). d=$(fresh) mkdir -p "$d/plugins/alpha/skills/half-added-skill" -check_fail "skill dir without SKILL.md still counted (drift caught)" "README.md Resources for 'alpha'" "$d" +check_fail "skill dir without SKILL.md still counted (drift caught)" "docs/plugins.md Resources for 'alpha'" "$d" # A skill added on disk but not reflected in the README Resources column. d=$(fresh) mkdir -p "$d/plugins/alpha/skills/second-skill" printf 'Second skill.\n' > "$d/plugins/alpha/skills/second-skill/SKILL.md" -check_fail "README skills drift vs disk fails" "README.md Resources for 'alpha'" "$d" +check_fail "README skills drift vs disk fails" "docs/plugins.md Resources for 'alpha'" "$d" # A plugin on disk (and in the manifests) with no README table row. d=$(fresh) # shellcheck disable=SC2016 -grep -v '`beta`' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" -check_fail "plugin missing from README table fails" "plugins/beta is not listed in the README.md plugin table" "$d" +grep -v '`beta`' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" +check_fail "plugin missing from README table fails" "plugins/beta is not listed in the docs/plugins.md plugin table" "$d" # --- check 6: bundled SKILL.md provenance --- # A skill whose frontmatter has its github-repo provenance stripped (e.g. hand-edited) @@ -469,20 +474,20 @@ check_fail "SKILL.md with comment-only github-repo fails" "missing upstream prov d=$(fresh) printf '%s\n' '{ "mcpServers": { "test-mcp": { "command": "test-mcp", "args": ["serve"] } } }' > "$d/plugins/alpha/.mcp.json" # shellcheck disable=SC2016 -sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-mcp` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-mcp` | Alpha plugin/' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_pass "plugin bundling a valid .mcp.json passes (MCP server in README resources)" "$d" # A remote (url) MCP server is equally valid. d=$(fresh) printf '%s\n' '{ "mcpServers": { "test-mcp": { "type": "http", "url": "https://example.com/mcp" } } }' > "$d/plugins/alpha/.mcp.json" # shellcheck disable=SC2016 -sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-mcp` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-mcp` | Alpha plugin/' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_pass "plugin bundling a remote (url) MCP server passes" "$d" # A bundled MCP server name missing from the README Resources column drifts out of lockstep. d=$(fresh) printf '%s\n' '{ "mcpServers": { "test-mcp": { "command": "test-mcp" } } }' > "$d/plugins/alpha/.mcp.json" -check_fail "MCP server missing from README resources fails" "README.md Resources for 'alpha'" "$d" +check_fail "MCP server missing from README resources fails" "docs/plugins.md Resources for 'alpha'" "$d" # An .mcp.json that is not valid JSON is rejected. d=$(fresh); printf '%s\n' 'not json' > "$d/plugins/alpha/.mcp.json" @@ -517,20 +522,20 @@ EOF d=$(fresh) mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" bare-agent.md # shellcheck disable=SC2016 -sed 's/`example-skill` | Alpha plugin/`example-skill`, `bare-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`example-skill` | Alpha plugin/`example-skill`, `bare-agent` | Alpha plugin/' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_fail "agent named bare .md fails (not VS Code/Copilot-discoverable)" "must use the .agent.md suffix" "$d" # A bundled agent name missing from the README Resources column drifts out of lockstep. d=$(fresh) mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.agent.md -check_fail "custom agent missing from README resources fails" "README.md Resources for 'alpha'" "$d" +check_fail "custom agent missing from README resources fails" "docs/plugins.md Resources for 'alpha'" "$d" # VS Code's discovery suffix (.agent.md, ADR 0001's 2026-07-18 correction) resolves to the # same README token as .md — the enumerator strips the whole .agent.md, never just .md. d=$(fresh) mkdir -p "$d/plugins/alpha/agents"; make_agent "$d/plugins/alpha/agents" test-agent.agent.md # shellcheck disable=SC2016 -sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_pass "agent named .agent.md resolves to in README resources" "$d" # An agents/ dir with no *.md (only a stray non-agent file) is not a valid agent resource. @@ -567,7 +572,7 @@ description: >- Body. EOF # shellcheck disable=SC2016 -sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`example-skill` | Alpha plugin/`example-skill`, `test-agent` | Alpha plugin/' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_pass "agent with a folded (>-) description passes" "$d" # A bare block-scalar description indicator with no body is empty ⇒ rejected. @@ -696,7 +701,7 @@ EOF sub("`example-skill`", "`agent-improvement`, `agent-improver`, `agentic-engineer`, `example-skill`, `portfolio-surveyor`") } { print } - ' "$root/README.md" > "$root/README.tmp" && mv "$root/README.tmp" "$root/README.md" + ' "$root/docs/plugins.md" > "$root/README.tmp" && mv "$root/README.tmp" "$root/docs/plugins.md" entrypoint_sha256=$(sha256_file "$root/plugins/$name/agents/agentic-engineer.agent.md") portfolio_surveyor_sha256=$(sha256_file "$root/plugins/$name/agents/portfolio-surveyor.agent.md") agent_improver_sha256=$(sha256_file "$root/plugins/$name/agents/agent-improver.agent.md") @@ -1211,7 +1216,7 @@ d=$(fresh); make_desired_state "$d" alpha rm "$d/plugins/alpha/agents/agent-improver.agent.md" # README resource names contain literal backticks. # shellcheck disable=SC2016 -sed 's/`agent-improver`, //' "$d/README.md" > "$d/tmp" && mv "$d/tmp" "$d/README.md" +sed 's/`agent-improver`, //' "$d/docs/plugins.md" > "$d/tmp" && mv "$d/tmp" "$d/docs/plugins.md" check_fail "plugin-backed schedule targets must resolve to bundled agents" \ "plugin-backed schedule target must resolve to a bundled agent" "$d" From 951cd7575b02999404c82669a8ddf68766138626 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 6 Sep 2026 16:26:28 +0200 Subject: [PATCH 2/4] docs: repair the version four migration link --- docs/resources.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/resources.md b/docs/resources.md index c8e6265c..4710d3e8 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -20,7 +20,7 @@ run — the (plugin identity), **then** the [version 3 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-3) (retire the `finops-engineer` schedule and adopt the `Spend contract` section), **then** the -[version 4 checklist](../plugins/agentic-engineering/README.md#migrating-to-the-agentic-engineer-entrypoint) +[version 4 checklist](../plugins/agentic-engineering/README.md#migrating-to-version-4) (the `automated-ai-engineer` → `agentic-engineer` entrypoint rename). Stopping early would resume unattended writes with the retired FinOps schedule still armed, or with a schedule pointing at an entrypoint that no longer resolves. @@ -104,4 +104,3 @@ consuming deployment must define the five contract sections (Portfolio map, Trus Memory, Maintainer channels) in its `AGENTS.md` — plus **Agent definition locations** and **Authority model** if it enables `agent-improver`, and **Spend contract** if it wants the engineer to steward spend (see the [plugin README](../plugins/agentic-engineering/README.md)). - From e327df2b28a25f209fe00fff25c2600ace57f447 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 6 Sep 2026 16:29:21 +0200 Subject: [PATCH 3/4] docs: normalize catalogue trailing whitespace --- docs/plugins.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/plugins.md b/docs/plugins.md index 9694036e..4adc6b1c 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -13,4 +13,3 @@ A **skill** teaches an assistant a task. An **agent** gives it a specialized rol | [`engineering-practices`](../plugins/engineering-practices/) | `conventional-release`, `git-commit`, `refactor`, `test-driven-development`, `ways-of-working` | Git commits, conventional releases, refactoring, TDD, and engineering ways of working | | [`frontend-design`](../plugins/frontend-design/) | `astro`, `frontend-design`, `web-design-guidelines` | Astro, frontend design, and web design guidelines | | [`vibe-coding`](../plugins/vibe-coding/) | `needs-stack-mapping`, `allowed-stack-guardrail`, `jargon-free-voice` (skills) · `vibe-coding-companion` (agent) | Build a product by conversation alone — plain-language companion agent + guardrailed needs-to-stack skills for people with no technical background | - From 097f5a09b21aa245993073c34191f3f7985b84bb Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sun, 6 Sep 2026 16:31:24 +0200 Subject: [PATCH 4/4] docs: clarify marketplace introduction and installation guides --- README.md | 4 ++-- docs/installation.md | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3600a777..24eed492 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Agent Plugins -Ready-to-install bundles that teach your AI coding assistant new skills, connect it to tools, and give it specialist roles. For developers using **VS Code**, **GitHub Copilot CLI**, or **Claude Code**. +A plugin marketplace: ready-to-install bundles that teach your AI coding assistant new skills, connect it to tools, and give it specialist roles. For developers using **VS Code**, **GitHub Copilot CLI**, or **Claude Code**. ## Start here @@ -11,7 +11,7 @@ In **Claude Code**, add the marketplace and install the GitHub tools bundle: /plugin install github@devantler-plugins ``` -Using another tool? Follow the [VS Code](docs/installation.md#vs-code), [Copilot CLI](docs/installation.md#copilot-cli), [Claude Desktop](docs/installation.md#claude-code), or [skills-only installation guide](docs/installation.md#any-other-agent--skills-only-via-npx-skills). +Using another tool? Follow the [VS Code](docs/installation.md#vs-code), [Copilot CLI](docs/installation.md#copilot-cli), [Claude Code](docs/installation.md#claude-code), or [skills-only installation guide](docs/installation.md#any-other-agent--skills-only-via-npx-skills). ## Choose a bundle diff --git a/docs/installation.md b/docs/installation.md index 2170fded..ae393ce5 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,6 +1,6 @@ # Installation -### VS Code +## VS Code Add the marketplace to your settings: @@ -13,7 +13,7 @@ Add the marketplace to your settings: Then open **Extensions**, search `@agentPlugins`, and install a plugin from this marketplace. Review the source when VS Code asks you to trust it. See the [VS Code plugin guide](https://code.visualstudio.com/docs/agent-customization/agent-plugins). -### Copilot CLI +## Copilot CLI Run these in your terminal; `devantler-plugins` is the marketplace name registered by the first command. See the [Copilot plugin reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference). @@ -28,7 +28,7 @@ copilot plugin marketplace browse devantler-plugins copilot plugin install gitops-kubernetes@devantler-plugins ``` -### Claude Code +## Claude Code Add the marketplace, then install a plugin — run these inside Claude Code ([official guide](https://code.claude.com/docs/en/discover-plugins)): @@ -41,9 +41,9 @@ Browse everything on offer with `/plugin` (**Discover** tab) or list it with `/p Claude Desktop can add the same GitHub repository from **Plugins → Personal**. That path validates the marketplace remotely in strict mode; every plugin therefore includes the canonical `.claude-plugin/plugin.json` manifest it requires. -### Any other agent — skills only, via `npx skills` +## Any other agent — skills only, via `npx skills` -[`npx skills`](https://github.com/vercel-labs/skills) reads this repo's [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) and installs the bundled **skills** into any of its 70+ supported agents — useful when your agent isn't one of the three above: +[`npx skills`](https://github.com/vercel-labs/skills) reads this repo's [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json) and installs the bundled **skills** into its supported agents — useful when your agent isn't one of the three above: ```sh # Browse the bundled skills without installing @@ -55,8 +55,8 @@ npx skills add devantler-tech/agent-plugins --skill gitops-knowledge --agent cur > [!IMPORTANT] > This is a **partial** install path. The example installs only `gitops-knowledge` for Cursor. Use -> `--all` to install every bundled skill across detected agents, or combine a pattern such as -> `--skill gitops-*` with `--agent cursor` to target that agent. None of these skills-only forms +> `--all` to install every bundled skill across detected agents, or choose another skill by name +> with `--skill ` and `--agent cursor` to target that agent. None of these skills-only forms > install the [MCP servers](resources.md#mcp-servers) or [custom agents](resources.md#custom-agents). To get everything a > plugin bundles, install it as a plugin in **VS Code**, **Copilot CLI**, or **Claude Code** above — > all three load a plugin's bundled `.mcp.json` and `agents/` automatically.