Conform to Agent Plugins 1.0.0 and the Agent Skills specification (v0.2.0) - #5
Merged
Conversation
Two independent fatal faults meant a conformant Agent Plugins client would
load nothing from this plugin:
1. plugin.json omitted the required $schema. It sits on a closed schema, so
§5.2 makes the omission fatal — the client rejects the plugin outright.
2. All 17 skills carried top-level frontmatter keys (version, triggers,
required_scopes, mcp_servers, persona, tier, gate, owns_eval) outside the
closed Agent Skills field set. Agent Plugins §6.1 requires clients to skip
every non-conforming skill.
Changes:
- plugin.json declares the manifest schema.
- New root mcp.json: the portable MCP manifest, with an explicit stdio
transport discriminator. It ships the gcloud server only — toolbox needs a
user-specific tools.yaml that no spec placeholder can express, so it stays a
documented opt-in. env is omitted entirely: only ${PLUGIN_ROOT} and
${PLUGIN_DATA} expand, so ${GCP_PROJECT_ID} would have been passed through
literally and mis-set the project.
- All 17 SKILL.md frontmatters reduced to {name, description, license,
metadata}. Routing keywords folded into description, which is what a
conformant client actually routes on; the plugin's own contract moves to
namespaced string values under metadata.
- validate_skills.py inverted: it now enforces the closed Agent Skills field
set instead of requiring the fields that broke conformance.
- New validate_agent_plugins.py: dependency-free conformance check wired in as
`make spec`, reporting against the spec's own FATAL/MCP/SKILL failure
boundaries.
- Smoke tests rewritten: 136 -> 195, covering both specs.
Verified against the official reference validator (agentskills/agentskills
skills-ref) — 17/17 valid — and both published JSON schemas via
check-jsonschema. All four harnesses remain installable.
…routing Documentation still described the contract the previous commit deleted, and a cross-harness routing test surfaced a real regression risk in the migration. ADR-007 records the adoption decision, its trade-offs, and why mcp.json is smaller than the harness manifests. ADR-005 is marked superseded — its reasoning for carrying the metadata still holds, only the location changed. Routing: with `triggers` gone, `description` is the sole routing signal. Loading the skills into Kimi via --skills-dir and putting five requests through it confirmed all 17 load and route correctly, but flagged four pairs whose descriptions both matched: iam/gcp-security, gcp-ops/logging-monitoring, vertex-ai/agent-architect, gcp-architect/solution-designer. Each now names its counterpart and draws the boundary explicitly. Also: - README gains a Standards and compliance section with the conformance table and commands to verify it without trusting this repo's own scripts. - shared/conventions.md and SPEC.md carry the closed field set and the rules for writing a description that routes. - skills/mcp-servers/references/agent-plugins-mcp.md explains the placeholder trap and documents toolbox as an opt-in. - `make manifest` no longer claims the plugin is "installable across 4 harnesses" — it checks that manifests parse and agree, and now says so. - .claude/CLAUDE.md claimed to be gitignored; it is tracked and public. .gitignore covers .claude/local-CLAUDE.md, so the guide is meant to ship — the self-description was simply wrong. make spec, validate, manifest and test all pass; skills-ref 17/17.
A Kimi routing test over the seven canonical requests returned 7/7 correct and confirmed three of the four disambiguated pairs resolved. It flagged the fourth as still ambiguous, correctly: vertex-ai's description told the reader to go to agent-architect for agentic work while still listing "Agent Builder" among the things it covers. The clause and the coverage list contradicted each other. vertex-ai now hands Agent Builder over explicitly along with ADK, Agent Runtime, A2A, AP2 and multi-agent topologies. agent-architect claims it in turn, in both its description and its trigger list — the redirect previously pointed at a skill that never mentioned the term. make spec, validate and test pass; skills-ref valid for both skills.
Kimi held the vertex-ai/agent-architect boundary ambiguous across two rounds and both times named the same phrase: vertex-ai claimed "generative AI applications", which reads as agentic and re-opened the overlap its own hand-off clause had just closed. Narrowed to "generative AI workloads — models, prompts, tuning and endpoints". Re-tested: 'build an agent with Vertex AI Agent Builder' now routes to agent-architect, and the pair reports RESOLVED. All four disambiguated pairs are clean.
Bumps every manifest to 0.2.0 and adds a changelog. The minor bump is warranted: the SKILL.md frontmatter contract changed shape, so anything reading the top-level triggers/required_scopes/mcp_servers lists breaks and must read the namespaced metadata keys instead. Pre-1.0, that is a minor. CHANGELOG.md records the standards adopted, what broke, why mcp.json declares one server and no env, and the verification evidence — including which harnesses were tested and which were not.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the plugin into conformance with Agent Plugins 1.0.0 and the Agent Skills specification — the open, vendor-neutral packaging standards co-maintained by Amazon, Cursor, Google, Microsoft, OpenAI and Vercel, announced here.
Before this PR, a conformant Agent Plugins client would have loaded nothing from this plugin. Two independent fatal faults:
plugin.jsonomitted the required$schema. The manifest schema is closed (additionalProperties: false), so §5.2 makes the omission fatal — the client rejects the plugin outright.version,triggers,required_scopes,mcp_servers, and on personaspersona,tier,gate,owns_eval). §6.1 requires clients to skip every non-conforming skill.Standards and specifications adopted
plugin.json,mcp.json,skills/layoutmake specplugin.schema.jsonmake spec+check-jsonschemamcp.schema.jsonmake spec+check-jsonschemaSKILL.mdmake validate+skills-refmcp.jsonserversKey decisions
mcp.jsondeclares noenv. Only${PLUGIN_ROOT}and${PLUGIN_DATA}expand; everything else passes through literally.CLOUDSDK_CORE_PROJECT: "${GCP_PROJECT_ID}"would have set the project to that 18-character string. Clients may inherit the ambient environment, andgcloud-mcpalready reads project + ADC from it.mcp.jsonshipsgcloudonly. Toolbox needs a user-specifictools.yamlpath no placeholder can express, so it stays a documented opt-in rather than a server guaranteed to fail on first run.plugin.jsonfield set and fixes component locations but says nothing about sibling directories..claude-plugin/,.kimi-plugin/,gemini-extension.jsonand.agents/are untouched.See ADR-007.
Breaking change (skill authors and downstream tooling)
Frontmatter is now
{name, description, license, metadata}. Plugin-specific fields move undermetadata, namespaced, as string values:Anything reading the old YAML lists must read the namespaced key and split on
", ". Routing keywords moved intodescription— the only field a conformant client routes on.No action for users. Existing installs are unaffected.
Verification
skills-ref— official Agent Skills reference validatorcheck-jsonschemavs both published schemasagy plugin validate— Antigravity loader--skills-dir)gcloud-mcp-serverv0.5.3, protocol 2025-06-18,run_gcloud_commandmake gate$schema, strip MCPtype, re-addtriggers— all 3 caughtReproduce without trusting this repo's own scripts:
uvx --from "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref" skills-ref validate skills/cloud-run uvx check-jsonschema --schemafile https://agent-plugins.org/schemas/1.0.0/plugin.schema.json plugin.jsonNot verified: Codex (usage limit at time of writing) and Toolbox MCP (opt-in by design).
Cross-harness testing found real defects
Every routing fix here came from the harnesses, not from review. With
triggersdeleted,descriptionis the sole routing signal — Kimi found four pairs where both skills matched the same request (iam↔gcp-security,gcp-ops↔logging-monitoring,vertex-ai↔agent-architect,gcp-architect↔solution-designer), then two follow-on contradictions invertex-ai. All fixed and re-tested to clean.Also
make specgate.make manifestno longer claims "installable across 4 harnesses" — it checks manifests parse and agree, and now says so..claude/CLAUDE.mdclaimed to be gitignored; it is tracked and public. Corrected.CHANGELOG.mdadded.