Multi-Harness Plugins & Project-Local .agents/ Architecture

Build and maintain skills, subagents, hooks, rules, and MCP configurations that work cleanly across Google Antigravity (IDE & CLI), Claude Code, Codex CLI, Cursor, OpenCode V2, and VS Code / GitHub Copilot—both for project-local .agents/ folders and extension-wide plugins.

Project-Local Discovery Matrix (.agents/ & Repo-Local Configs)

How each harness discovers project-local instructions, skills, subagents, hooks, and MCP servers inside a repository:

Workflow

1. Choose the Target Scope:
   • Project-Local (.agents/ inside a repository): Used by /flow:setup, /flow:learn, and repository maintainers to store .agents/bundles/ knowledge, .agents/skills/<domain>/ domain and review skills, .agents/agents/<name>.md subagents, .codex/agents/<name>.toml agents, and .agents/mcp_config.json / .mcp.json server definitions.
   • Extension-Wide Plugin (Plugin Repository Root): Used when packaging reusable skills, subagents, hooks, rules, and MCP servers as an installable plugin across all six harnesses.
2. Author Progressive-Disclosure Skills:
   • Keep every SKILL.md concise (<= 200 lines and strictly < 24,000 bytes so Google Antigravity never truncates the bottom of the file).
   • Start description with Use when ... (<= 500 characters) and avoid vague prefixes (Auto-activate, Produces, Expert knowledge, Comprehensive).
   • Put detailed schemas, checklists, and examples in references/*.md files linked from SKILL.md.
3. Author Compatible Subagents:
   • Format Markdown subagents (agents/<name>.md or .agents/agents/<name>.md) with name, description, model: inherit, mainAgent: false, subagent: true, commandExecutionPolicy, skills: [...], and readonly: true + YAML list disallowedTools for read-only reviewers.
   • Use top-level H1 (# ) section headings (# Role & Identity, # Responsibilities, # Verification & Constraints, # Output Contract) with ### subsections so Antigravity splits sections into XML system-prompt blocks.
   • Pair Markdown subagents with .codex/agents/<name>.toml for Codex CLI.
4. Keep Runtime Hooks Zero-Dependency & Cross-Platform:
   • Do not require python3, node, or jq in SessionStart shell hooks (agy and codex ship as static native binaries).
   • Pair pure POSIX sh + awk (hooks/<name>.sh) with native PowerShell (hooks/<name>.ps1, pwsh / Windows PowerShell 5.1+) and "commandWindows" for Windows hosts, plus .opencode/plugins/<name>.js in native node:fs / node:path.
5. Validate Structural Parity:
   • Run /flow:validate to verify SKILL.md byte budgets, subagent frontmatter and H1 headings, hook schemas, and relative links.

Guardrails

• No Duplicate Surface Mirrors: Never maintain plugins/<name>/ mirrors, root CLAUDE.md files alongside AGENTS.md (breaks claude plugin validate --strict and double-loads with AGENTS.md in Cursor), .github/agents/*.agent.md copies, .opencode/agents/*.md copies, or commands/ wrappers.
• Strict 24 KB SKILL.md Cap: Never exceed 24,000 bytes in any SKILL.md file.
• YAML List Tool Restrictions: Always format tools and disallowedTools as YAML lists (- Edit), never comma-separated strings (tools: Read, Grep fails YAML unmarshaling in Antigravity and silently drops the subagent).
• Short MCP Server & Tool Names: Keep combined MCP tool names under 60 characters (^[a-zA-Z0-9_-]+$) so Cursor (59-char cap) and Antigravity (64-char cap on mcp_<plugin>_<server>_<tool>) never drop or truncate tools.

References

• Skills, Subagents, Local .agents/, & MCP Limits — How each harness loads .agents/ folders, local MCP configs (.agents/mcp_config.json, .mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json), H1 subagent sections, and Antigravity's Python run_workflow API.
• Hooks & Runtime Portability — Project-local and plugin hook schemas (flat Antigravity lifecycle hooks vs. nested Claude/Codex matchers), stdout JSON keys, Cursor deduplication, and OpenCode V2 setup(ctx).
• Manifests & Single-Root Packaging — Root layout and manifest schemas for plugin.json, .claude-plugin/, .codex-plugin/, .cursor-plugin/, .agents/plugins/marketplace.json, package.json, and OpenCode V2.

Validation

• Confirm every SKILL.md has name and description (Use when ..., <= 500 chars) and is < 24,000 bytes.
• Confirm every subagent in agents/*.md or .agents/agents/*.md includes model: inherit, mainAgent: false, subagent: true, H1 (# ) section headings, and YAML list disallowedTools on read-only agents.
• Confirm all relative Markdown links resolve on disk.

Example

Invoke this skill when scaffolding project-local skills, subagents, hooks, or MCP configs under .agents/ during /flow:setup or /flow:learn, or when authoring an extension-wide multi-harness plugin.