Verify validate.sh checks match upstream platform specs. Use when reviewing changes to validation logic, updating allowed fields, or checking for spec drift.
This skill contains vendored specifications for every platform agent-validate checks. Use it to verify that validate.sh matches what upstream projects actually require.
When reviewing a PR that changes validation logic in validate.sh:
When updating validate.sh for a new upstream spec version:
references/Source: https://agentskills.io/docs/specification / https://raw.githubusercontent.com/agentskills/agentskills/main/docs/specification.mdx
Reference validator: https://github.com/agentskills/agentskills/tree/main/skills-ref
Vendored: references/agentskills-specification.mdx
Last verified: 2026-03-16
This is the canonical source of truth for SKILL.md validation. The Agent Skills open standard defines:
Required frontmatter: name, description.
Optional frontmatter: license, compatibility, metadata, allowed-tools.
Field allowlist: Only name, description, license, allowed-tools, metadata, compatibility are permitted. The reference validator (skills-ref validate) rejects any other fields.
Name constraints: 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing hyphens, no consecutive hyphens, must match parent directory name.
Description constraints: Non-empty string, max 1024 chars.
Compatibility constraints: Max 500 chars if present.
What validate.sh checks: All of the above, plus:
user-invocable accepted with a portability warning (used by Claude Code for slash menu visibility; not in the spec)argument-hint accepted with a portability warning (used by Pi for CLI hint display; not in the spec)disable-model-invocation accepted with a portability warning (used by Pi to hide skills from system prompt; not in the spec)--skip skill-name-matchskills, tools, or howto) get warnings instead of errors for name mismatchskills/, .agents/skills/, .claude/skills/, .opencode/skills/, plugins/*/skills/Quality warnings (non-blocking, all emit Warning: to stderr):
use when, use for, use if, use this, when you need, invoke when, trigger when, designed for) — the spec recommends describing both what and when](path) links that don't resolve from the skill directory (URLs and fragment-only links are excluded)Source: https://code.claude.com/docs/en/plugins-reference.md
Vendored: references/claude-plugins-reference.md
Last verified: 2026-03-16
Required fields: name only (manifest itself is optional).
Metadata fields (all optional): version, description, author, homepage, repository, license, keywords.
Component path fields (all optional): commands, agents, skills, hooks, mcpServers, outputStyles, lspServers. Each accepts string|array (some also accept object for inline config).
What validate.sh checks: Field allowlist covering all metadata and component path fields. Rejects any key not in the allowlist. Also runs claude plugin validate for structural checks (tier 2). Handles malformed JSON gracefully (error, not crash).
Source: https://code.claude.com/docs/en/plugin-marketplaces.md
Vendored: references/claude-plugin-marketplaces.md
Last verified: 2026-03-16
Required top-level fields: name, owner (with required owner.name), plugins array.
Optional top-level: metadata.description, metadata.version, metadata.pluginRoot.
Per-plugin required: name, source.
Per-plugin optional: description, version, author, homepage, repository, license, keywords, category, tags, strict, commands, agents, hooks, mcpServers, lspServers.
strict (boolean, default true): when false, plugin.json is not the authority for component definitions.
Source types: relative paths, GitHub repos (github:owner/repo), git URLs, npm packages. Only relative paths are validated for resolution.
What validate.sh checks: Validates name, owner.name, and plugins array are present. Rejects source paths containing ... Checks relative source paths resolve to directories. Cross-checks per-plugin name, version, description against sub-plugin manifests. Runs claude plugin validate on each non-strict-false sub-plugin.
Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/reference.md
TypeScript interface: https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/config/extension.ts
Vendored: references/gemini-extension-reference.md, references/gemini-extension-config.ts
Last verified: 2026-03-16
Interface fields: name (string, required), version (string, required), mcpServers (optional), contextFileName (string or string[], optional), excludeTools (string[], optional), settings (ExtensionSetting[], optional), themes (CustomTheme[], optional), plan (object with optional directory, optional), migratedTo (string, optional — migration URL for repository moves).
Documentation also mentions: description, policy engine (.toml files in policies/ directory).
description gap: The description field appears in the reference docs but is NOT in the ExtensionConfig TypeScript interface. validate.sh includes it in the allowlist based on the docs.
Sub-components: Gemini CLI supports extension sub-components: commands/*.toml (command definitions), hooks/hooks.json (lifecycle hooks), agents/*.md (agent definitions), policies/*.toml (policy rules). validate.sh checks JSON/TOML syntax and agent frontmatter when these directories exist. TOML checks require taplo on PATH.
gemini skills CLI: Gemini CLI provides gemini skills list / gemini skills install commands for standalone skill management. validate.sh checks installed skills via gemini skills list in Tier 3 deployment verification.
contextFileName can be a string or array of strings. If omitted and GEMINI.md exists, that file is loaded. When an array, each entry is resolved independently.
What validate.sh checks: Cross-checks name, version, description against plugin.json/package.json. Validates contextFileName file(s) exist — handles both string and array forms. Validates name format (lowercase alphanumeric with dashes). Field allowlist covering all ExtensionConfig interface fields: name, version, description, mcpServers, contextFileName, excludeTools, settings, themes, plan, migratedTo — rejects any key not in the allowlist. Handles malformed JSON gracefully. Validates sub-component syntax: hooks/hooks.json (JSON), commands/*.toml and policies/*.toml (TOML via taplo), agents/*.md (YAML frontmatter). Tier 3 deployment verifies installed skills via gemini skills list.
Source: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
Vendored: references/pi-readme.md
Last verified: 2026-03-16
The pi key in package.json can contain: extensions, skills, prompts, themes — each a string or array of directory paths. It can also contain video and image — URL strings for the package gallery preview (not file paths).
Without a pi manifest, pi auto-discovers from conventional directories (extensions/, skills/, prompts/, themes/).
Pi packages should include "keywords": ["pi-package"] for discovery.
What validate.sh checks: Extracts top-level .pi entry values via jq, skips URL values (https?://), verifies remaining values resolve as paths. Warns if keywords does not include "pi-package". Also checks for TypeScript syntax in extensions/*.ts.
Source: https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md
Vendored: references/pi-skills.md
Last verified: 2026-03-16
Pi 0.56.0 documents skill frontmatter in docs/skills.md. In addition to the Agent Skills specification fields, Pi recognizes:
disable-model-invocation (boolean): when true, the skill is hidden from the system prompt; users must invoke it explicitly via /skill:name.Pi ignores unknown frontmatter fields (they don't cause errors in Pi itself). validate.sh treats disable-model-invocation as a known extension and emits a portability warning rather than an error.
Source: No formal specification. Codex uses AGENTS.md (shared with OpenCode) and codex.md for agent instructions.
What validate.sh checks: Detects presence of AGENTS.md and/or codex.md. Runs markdownlint on detected files (unless markdown is skipped). No structural validation beyond markdown lint — no known schema or field requirements exist yet.
What validate.sh doesn't check: File content structure, frontmatter, or any Codex-specific conventions. If Codex publishes a spec in the future, add structural checks here.
Source: No formal specification. OpenCode uses AGENTS.md for agent instructions.
What validate.sh checks: Detects presence of AGENTS.md. Runs markdownlint on the file (unless markdown is skipped). No structural validation beyond markdown lint.
What validate.sh doesn't check: File content structure or any OpenCode-specific conventions. If OpenCode publishes a spec in the future, add structural checks here.
Deployment checks are opt-in via --check-deploy. They verify installed
state on the host, not repo structure. Off by default — CI runners typically
lack agent CLIs in the right state.
Requires claude binary on PATH. Parses claude plugin list --json and
claude plugin marketplace list --json. Checks:
.id prefix (name@marketplace format)Requires gemini binary on PATH. Parses gemini extensions list -o json.
Checks:
.isActive is true (not just installed)gemini skills list (first-class skill management)No CLI needed — checks directory presence. Checks:
~/.agents/skills/ (or $AGENTS_SKILLS_DIR if set)description gap: The description field appears in the extension reference docs but is not in the ExtensionConfig TypeScript interface. The allowlist includes it based on the documentation.! negation globs: Pi supports !-prefixed exclusion patterns in package.json pi arrays (e.g., "!prompts/README.md"). This behavior is not documented in pi-readme.md but is observed in practice. validate.sh skips !-prefixed values during path resolution.plan field shipped (0.33.1) (2026-03-16): The plan field is now present in the stable ExtensionConfig interface and reference docs. Drift note removed.migratedTo field added (0.33.1) (2026-03-16): New migratedTo field for extension repository migration. Added to allowlist with test fixture.extensions validate exits 41 in headless CI because the CLI gates on auth config before dispatching any subcommand. Fix: validate.sh sets GEMINI_API_KEY (if unset) to a dummy value before Gemini CLI calls — the validate subcommand never calls the API.video and image fields in .pi are URL strings for the package gallery, not file paths. The jq extraction now skips https?:// values only for video/image keys.disable-model-invocation misclassified (2026-03-05): Pi 0.56.0 documents this SKILL.md frontmatter field in docs/skills.md. Previously rejected as an unknown field; now accepted with a portability warning.hooks/hooks.json, commands/*.toml, policies/*.toml, and agents/*.md frontmatter.gemini-extension.json against ExtensionConfig interface. Added plan drift documentation.AGENTS.md/codex.md files are now markdownlinted.Vendored reference documents are in references/. To update:
When adding validation support for a new platform, complete every item:
references/<platform>-<docname>.<ext>--skip <platform> value and document it in usage()# Ref: comments citing vendored reference file and line rangestests/fixtures/<platform>-valid/ with a minimal passing casetests/fixtures/<platform>-broken/ with at least one failing caseassert_pass / assert_fail / assert_fail_stderr entries in tests/run.sh.github/workflows/spec-freshness.ymlNEW_PLATFORM_SHA).github/workflows/cli-regression.yml--skip value to action.yml documentation (if visible to consumers).github/copilot-instructions.md review checklistSearch for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer