agent-plugins-validate

Make sure your Agent Plugin actually loads, before anyone installs it.

An Agent Plugin is a package of skills and MCP servers that AI clients load, described by a plugin.json and an mcp.json. This GitHub Action checks both against the Agent Plugins specification. When something's wrong, it tells you exactly what, and how to fix it, right in your pull request.

Add this file to your repository as .github/workflows/agent-plugins.yml:

name: agent-plugins
on: [push, pull_request]
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: rbadillap/agent-plugins-validate@32d0b41fe1d3881049730c9120660298adcec37d # v1.0.0

That's it. No configuration, no tokens, no secrets.

If something's wrong, a note appears on the exact line of your pull request:

❌ mcp.json, line 9 mcpServers.docs.type is "http". Use "streamable-http". Clients that follow the spec skip this server until it's fixed. Spec: §7.2.1 https://github.com/agentplugins/agent-plugins-spec/blob/v1.0.0/spec/1.0.0.md#721-discovery-and-configuration

And the run's summary gives you the full picture:

Agent Plugins manifests

✅ plugin.json follows the spec.

❌ mcp.json has 1 thing to fix.

	File	Field	Now	How to fix	Spec
❌	mcp.json	mcpServers.docs.type	"http"	use "streamable-http"	§7.2.1

When everything is right, the check turns green and the summary simply says so: "Both manifests follow the Agent Plugins spec (1.0.0)."

Every rule cites a section of the spec. The most common ones, by file:

All the rules, with what each one checks and its spec section, are in docs/rules.md.

Levels follow what the spec says a client does with the problem:

• Error: a client rejects the plugin, turns off its MCP servers, or skips a server. Fails the check.
• Warning: the spec requires it, but a client reports the problem and keeps loading, such as an unknown top-level field in plugin.json (§5.2). Doesn't fail.
• Notice: something the spec recommends (SHOULD) but doesn't require, such as a Semantic Versioning version (§10.2). Doesn't fail.

      - uses: rbadillap/agent-plugins-validate@32d0b41fe1d3881049730c9120660298adcec37d # v1.0.0
        with:
          manifests: plugins/*/plugin.json

      - id: manifests
        uses: rbadillap/agent-plugins-validate@32d0b41fe1d3881049730c9120660298adcec37d # v1.0.0
      - if: always() && steps.manifests.outputs.findings != '0'
        run: echo "Something to look at, see the summary of this run"

The format of each finding, and the JSON Schema of the report, are in docs/report.md.

This is the one place for what the Action can reach.

• No network. With open-issues off, the Action makes no HTTP, DNS or socket use at all. With it on, it talks only to GitHub's API, to read the previous version of your manifests and to manage its own issues. No telemetry. The schemas are bundled, so nothing is downloaded.
• No secrets. It reads none and has no token of its own. With open-issues on, it uses the token input, which defaults to the workflow's GITHUB_TOKEN.
• Small writes. The step outputs, the job summary, the JSON report in the runner's temporary directory and, only if you opt in, its own issues. It never comments on pull requests, pushes commits or touches issues it didn't open.
• Your files. It reads only files named plugin.json or mcp.json inside your checkout, never follows a link out of it, and never runs what it reads. What your manifests contain is treated as untrusted text in annotations, summaries and issues.

It has no opinion on how your MCP servers authenticate or confirm writes. The spec leaves those to the client.

Issues are off by default. To turn them on, give the job issues: write and set open-issues:

name: agent-plugins
on:
  push:
permissions:
  contents: read
  issues: write
concurrency:
  group: agent-plugins-validate-${{ github.ref }}
  cancel-in-progress: false
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: rbadillap/agent-plugins-validate@32d0b41fe1d3881049730c9120660298adcec37d # v1.0.0
        with:
          open-issues: true

• Only on your default branch, whatever its name. On other branches and on pull requests it does nothing.
• Only real regressions: a check that passed at the commit before the push and fails now. No proof, no issue.
• One issue per problem, never repeated, with the agent-plugins-validate label. It only ever touches issues it opened.
• Closed by the fix. When the check passes again, the issue closes with a comment naming the commit.
• Errors and warnings only. Notices never open issues.

How it decides, what it tracks and its limits are in docs/issues.md.

To keep a SHA up to date, let Dependabot open the pull requests. It updates the SHA and the version comment together. Add this to .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

The Marketplace's "Use latest version" button gives a tag, not a SHA. Replace the tag with the commit it points to, as above.

Every release is immutable and has a build attestation. To check that the dist/index.js you run was built by this repository's release workflow, download it from the tag you use and verify it (how releases are made):

gh attestation verify dist/index.js --repo rbadillap/agent-plugins-validate

A new check arrives as a warning (or notice) in a minor release, and becomes an error only in the next major release.

The checks follow Agent Plugins 1.0.0. The official schemas ship inside this Action, in schemas/, under their own Apache-2.0 license (notice, license text). A manifest that declares a version this Action doesn't support gets one finding saying so, never a guess.

MIT. The bundled schemas keep their Apache-2.0 license.