You’re probably hearing more about SKILL.md files, and you’ll see that a lot of people test them the same way: paste a prompt into chat, watch it pass once on a laptop, and merge to main. But when you paste three pages of CLI docs into a markdown file without an evaluation loop, you are just as likely to confuse a frontier model as you are to help it.
For the past weeks, we have been diligently measuring and optimizing our own Google Cloud Developer Plugin, with the most essential skills and the Developer Knowledge MCP server to ground responses in the documentation.
We ran dozens of scenarios with Gemini, Antigravity, and other agents. We used Claude Sonnet 5 on Gemini platform inside isolated Harbor pods on GKE Autopilot. And, we contributed Kubernetes and Gemini platform capabilities upstream to NVIDIA’s open-source evaluator.
Here’s the five-rule engineering playbook we use to verify a skill is worth its tokens.
1. Gate trigger collisions and security risks before spinning up containers
When an evaluation run shows zero improvement between your plugin arm and your baseline arm (Δ = 0), the natural urge is to rewrite the body of your SKILL.md instructions. Hold off on that. Nine times out of ten, the agent never loaded your skill in the first place.
Coding agents do not read full SKILL.md bodies at turn zero. The router only inspects the short name and description in your YAML frontmatter. Once a workspace grows past a dozen skills, two failure modes collide: under-triggering (your description describes internal implementation rather than developer intent) and sibling hijacking (a broad phrase like “helps with cloud deployments” in a neighboring skill intercepts the prompt first).
We recently open-sourced skill-reach so you can catch frontmatter collisions before spending on container sandboxes. It validates manifests, computes vocabulary overlap against nearest rival skills, and runs empirical routing probes across Claude Code, Google Antigravity, and OpenAI Codex:
