check-agent-compatibility

Check agent compatibility

Contract

Inputs

• Repository path to audit (must be supplied).
• Optional scope limit (subdirectory or file glob) narrowing the pass; when omitted the whole repository is audited.

Procedure

1. Parse scope and bind to the repository. Resolve the repository path to an absolute directory and apply the optional scope limit. Do not widen scope mid-pass. Done when: scope is bound to the repository path and optional limit.
2. Discover agent configuration and instruction surfaces. Scan for: .claude/ directories (settings.json, commands/, hooks/), CLAUDE.md and AGENTS.md files, .cursor/ directories, plugin.json or .claude-plugin/ manifests, agents/openai.yaml skill manifests, MCP configuration files (.mcp.json, mcp.json), and any skills/*/SKILL.md trees. Done when: all agent configuration and instruction surfaces within scope are discovered.
3. Validate syntax, schema, and dependency resolution for discovered surfaces. For each surface: parse JSON/YAML syntax, check required schema fields against the expected format, and verify that referenced files (entry points, hook scripts, skill directories) exist and resolve. Done when: every discovered surface is validated or its validation error is recorded.
4. Run read-only agent startup and configuration loading. Attempt to load the agent configuration as the host would: parse settings, resolve hook definitions without executing them, resolve tool permissions, and load skill manifests. Registering a hook in the host runs its command, so resolve and validate hook definitions only; do not register or run them. Capture any startup errors, missing dependencies, or configuration conflicts. Do not execute any tool or mutation. Done when: startup and configuration loading is attempted, hook definitions are resolved without execution, and results are captured.
5. Aggregate findings into a scored compatibility report. Score each of the four dimensions on a 0-100 scale:
   • Configuration validity (syntax, schema, field completeness)
   • Instruction reliability (documented instructions match observed repository behavior)
   • Startup readiness (configuration loading and tool registration succeed without mutation)
   • Dependency resolution (referenced files, entry points, and skill paths resolve) Compute the composite as the unweighted average of available dimension scores. A dimension that could not be evaluated contributes no score and does not lower the composite. Rank findings by impact on agent compatibility. Done when: the scored report with prioritized fixes is produced.