Compatibility Matrix

10. Cross-Platform Compatibility Matrix

Artifact Support by Platform

Artifact	Claude Code	Cursor	Copilot	Codex	Standard	Confidence
Skills (SKILL.md)	✅ Native	✅ v2.2+	⚠️ .github/skills/ (Preview)	✅ CLI+App	agentskills.io	Community
Commands	✅ Native	⚠️ Via rules	✅ .prompt.md	⚠️ Via skills	Package-defined	Official
Agents	✅ Native (agents/<name>/ dir)	⚠️ Via rules	✅ .agent.md	⚠️ Via skills	Package-defined	Official
Rules / Instructions	✅ CLAUDE.md	✅ .cursor/rules/*.mdc	✅ .instructions.md	⚠️ AGENTS.md	Package-defined	Official
AGENTS.md	✅	✅	✅†	✅	agents.md	Official
Hooks	✅ 10 events	⚠️ 5 events (Community)	⚠️ 4 events (Inferred)	❌	Package-defined	Mixed
MCP Servers	✅ Native	✅ Native	✅ CCA + VS Code	⚠️ Limited	MCP Protocol	Official

Instruction File Compatibility

File	Claude Code	Cursor	Copilot	Codex	Jules	Confidence
AGENTS.md	✅	✅	✅†	✅	✅	Official
CLAUDE.md	✅	✅*	❌	❌	❌	Official
GEMINI.md	❌	✅*	❌	❌	❌	Community
.cursor/rules/*.mdc	❌	✅	❌	❌	❌	Official
.github/copilot-instructions.md	❌	❌	✅	❌	❌	Official
.github/instructions/*.instructions.md	❌	❌	✅	❌	❌	Official
.github/agents/*.agent.md	❌	❌	✅	❌	❌	Official

*Cursor reads CLAUDE.md and GEMINI.md as agent-specific instruction files alongside AGENTS.md.

†GitHub Copilot reads AGENTS.md only in Copilot Coding Agent (autonomous agent) mode. Standard Copilot chat does not read this file.

GitHub Copilot Artifact Types

Artifact	Location	Format	Description
Repo instructions	.github/copilot-instructions.md	Plain Markdown	Repository-wide guidance
Path instructions	.github/instructions/*.instructions.md	YAML frontmatter (applyTo glob) + Markdown	Path-scoped rules
Custom agents	.github/agents/*.agent.md	Markdown	Agent definitions (VS Code)
Agent instructions	AGENTS.md / CLAUDE.md / GEMINI.md	Plain Markdown	Agent-specific instructions

Path Instructions Example

---
applyTo: "src/**/*.ts"
---

# TypeScript Standards
- Use strict mode
- Prefer interfaces over type aliases

Platform Capability Discovery

Static compatibility matrices become outdated. To enable runtime discovery, platforms implementing UAAPS Level 2+ SHOULD expose a capabilities object queryable by packages and tools.

Capabilities Object Schema

{
  "platform": "claude-code",
  "platform_version": "1.4.2",
  "uaaps_conformance_level": 2,
  "spec_version": "0.6.0",
  "supported_artifacts": ["skills", "commands", "agents", "rules", "hooks", "mcp"],
  "hook_events": [
    "pre-tool-use", "post-tool-use", "pre-prompt", "stop",
    "session-start", "session-end", "sub-agent-end",
    "permission-request", "pre-compact", "notification"
  ],
  "permissions_enforcement": {
    "fs": true,
    "network": true,
    "shell": true
  },
  "eval_headless": true,
  "resolver_version": 1
}

Capabilities Field Reference

Field	Type	Required	Description
platform	string	Yes	Platform identifier (e.g. claude-code, cursor, copilot, codex).
platform_version	string	Yes	Platform version string.
uaaps_conformance_level	number	Yes	Declared conformance level (1, 2, or 3). See §1 Conformance Levels.
spec_version	string	Yes	Highest UAAPS spec version supported.
supported_artifacts	string[]	Yes	Artifact types the platform can consume.
hook_events	string[]	Yes	Hook event names the platform fires.
permissions_enforcement	object	Yes	Which permission categories are enforced at runtime.
eval_headless	boolean	Yes	Whether the platform supports headless eval execution.
resolver_version	number	No	Dependency resolver version supported. Default 1.

Querying Capabilities

# CLI query
aam platform info
aam platform info --json

# Programmatic (within a hook or skill script)
# Read from well-known path: .agent-packages/.platform-capabilities.json
# Written by the platform on session start

Platforms MUST write the capabilities object to .agent-packages/.platform-capabilities.json at session start. Packages MAY read this file to adapt behavior based on platform support (e.g., falling back to AGENTS.md injection when hooks are unsupported).

Graceful Degradation

When a package requires an artifact type or hook event not listed in the platform's capabilities:

Situation	Behavior
Unsupported artifact type	aam install emits a WARN: "Platform does not support <type>. These artifacts will be ignored." Installation proceeds.
Unsupported hook event	Hook entry is skipped silently. Platform MAY log at debug level.
Missing permission enforcement	aam install emits a WARN: "Platform cannot enforce <category> permissions. Package runs with platform defaults."
Lower conformance level than package requires	aam install emits a WARN listing which features will be unavailable.