From 4a611fcf8ecf0c75c4b35ec810ba6c4cd5078169 Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Thu, 15 Oct 2026 09:39:54 +0200 Subject: [PATCH 1/2] chore: expose agent rules and skills to agy via AGENTS.md and .agents/skills AGENTS.md is a relative symlink to CLAUDE.md and .agents/skills a relative symlink to ../.claude/skills, mirroring the existing .claude/commands link. The Antigravity CLI (agy 1.3.5) loads AGENTS.md as its workspace rule file and lists all ten project skills from .agents/skills (verified locally); Codex and the Copilot coding agent read AGENTS.md too. One source, no third file to keep in sync. A unit test pins both links (symlink, relative target, resolves to the Claude source). CLAUDE.md and the project guide document the bridge and say that Claude-specific tool wording applies to other agents by analogy. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GdMSqLR5ww4ji74EUSmk9M --- .agents/skills | 1 + .github/copilot-instructions.md | 2 +- AGENTS.md | 1 + CLAUDE.md | 1 + agentic/docs/project-guide.md | 1 + changelog.d/agents-md-bridge.md | 8 ++++++++ tests/unit/test_agent_instructions.py | 23 +++++++++++++++++++++++ 7 files changed, 36 insertions(+), 1 deletion(-) create mode 120000 .agents/skills create mode 120000 AGENTS.md create mode 100644 changelog.d/agents-md-bridge.md diff --git a/.agents/skills b/.agents/skills new file mode 120000 index 00000000000..454b8427cd7 --- /dev/null +++ b/.agents/skills @@ -0,0 +1 @@ +../.claude/skills \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3f6a809ef87..e59dd652879 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -322,7 +322,7 @@ uv run alembic upgrade head - **Documentation**: Check `docs/` directory for architecture, workflow, and development guides - **Examples**: Look at existing plot implementations in `plots/` for patterns -- **CLAUDE.md**: Additional guidance specific to Claude AI agent workflows +- **CLAUDE.md**: Additional guidance specific to Claude AI agent workflows; `AGENTS.md` is a symlink to it, so agents that read `AGENTS.md` get the same rules - **Issue Templates**: Use GitHub issue templates for consistent problem reporting ### Common Issues diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 00000000000..681311eb9cf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 2283962b857..4845243ae7a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,6 +93,7 @@ Known gaps with NO verification loop yet (reason through carefully and say so in ## Claude Code Configuration - **Commands directory**: Commands live in `agentic/commands/` (agent-agnostic). A symlink `.claude/commands/ → ../agentic/commands/` ensures Claude Code slash-command resolution works. Do not create commands directly in `.claude/commands/`. +- **Other agents read the same files**: `AGENTS.md` is a symlink to this file and `.agents/skills/ → ../.claude/skills/` exposes the project skills, so the Antigravity CLI (`agy`), Codex, and other tools that read `AGENTS.md` or `.agents/skills/` load the same rules and skills. Edit `CLAUDE.md` and `.claude/skills/`, never the link paths, and never replace either link with a real file or directory. Rules worded for Claude Code tools (Edit/Write, `model: opus`, subagents, MCP servers) apply to other agents by analogy: their file-editing tool, their strongest model tier, their delegation mechanism. ## CRITICAL: Mandatory Workflow for New Specs and Implementations diff --git a/agentic/docs/project-guide.md b/agentic/docs/project-guide.md index fee3d069e2e..2fd9dcd1cef 100644 --- a/agentic/docs/project-guide.md +++ b/agentic/docs/project-guide.md @@ -206,6 +206,7 @@ Example: `plots/scatter-basic/` contains everything for the basic scatter plot. - **`agentic/`**: AI workflow layer (composable phases, prompt templates, runtime state) - **`agentic/workflows/`**: Click CLI scripts (plan, build, test, review + orchestrators) - **`agentic/commands/`**: Markdown prompt templates +- **Agent instruction files**: `CLAUDE.md` holds the rules and `.claude/skills/` the skills. Three symlinks make them visible to other tools without a copy to keep in sync: `.claude/commands/` points to `agentic/commands/`, `AGENTS.md` points to `CLAUDE.md` (read by the Antigravity CLI `agy`, Codex, and the GitHub Copilot coding agent), and `.agents/skills/` points to `.claude/skills/` (the skills directory `agy` reads). `.github/copilot-instructions.md` is the separate, hand-synced guide for Copilot. `tests/unit/test_agent_instructions.py` fails if a link is replaced by a real file or points elsewhere. - **`automation/`**: CI/CD helper scripts (workflow_cli, label_manager, sync_to_postgres) - **`infra/`**: Infrastructure that would otherwise live only in a dashboard - **`infra/cloudflare/`**: Source of the apex `anyplot.ai/api/*` Worker, plus the origin gate's rollout and measuring procedure diff --git a/changelog.d/agents-md-bridge.md b/changelog.d/agents-md-bridge.md new file mode 100644 index 00000000000..3e7c8310fc2 --- /dev/null +++ b/changelog.d/agents-md-bridge.md @@ -0,0 +1,8 @@ +### Added + +- **Agent rules and skills for non-Claude agents.** `AGENTS.md` is a symlink to + `CLAUDE.md` and `.agents/skills/` a symlink to `.claude/skills/`, so the + Antigravity CLI (`agy`), Codex, and other tools that read those paths load the + same rules and skills from one source instead of a third file to keep in sync. + A unit test fails if either link is replaced by a real file or points + elsewhere. diff --git a/tests/unit/test_agent_instructions.py b/tests/unit/test_agent_instructions.py index c6fd2608f76..6dc80c0c64b 100644 --- a/tests/unit/test_agent_instructions.py +++ b/tests/unit/test_agent_instructions.py @@ -235,6 +235,29 @@ def test_the_commands_symlink_points_where_it_says() -> None: assert link.resolve() == (REPO_ROOT / "agentic" / "commands").resolve() +@pytest.mark.parametrize( + ("link", "target", "raw"), + [ + (REPO_ROOT / "AGENTS.md", CLAUDE_MD, "CLAUDE.md"), + (REPO_ROOT / ".agents" / "skills", REPO_ROOT / ".claude" / "skills", "../.claude/skills"), + ], + ids=["AGENTS.md", ".agents-skills"], +) +def test_the_agents_bridge_links_point_at_the_claude_sources(link: Path, target: Path, raw: str) -> None: + """`AGENTS.md` and `.agents/skills/` are how agy, Codex and other non-Claude + agents find the rules and skills (CLAUDE.md, "Claude Code Configuration"). + + Same failure as the commands link: a real file or directory in their place + still exists and still reads plausibly, but it is a third copy nobody keeps + in sync. The raw link text is pinned as well, because a relative link is + what keeps it valid in every checkout and worktree; an absolute one resolves + on the machine that made it and nowhere else. + """ + assert link.is_symlink(), f"{link} is documented as a symlink" + assert link.readlink() == Path(raw), f"{link} should be the relative link {raw}" + assert link.resolve() == target.resolve() + + def test_every_named_skill_exists() -> None: """The routing table in CLAUDE.md sends work to `.claude/skills//`. From a62b7e07d4e2693f428c1e3af2fdc8646ea197ad Mon Sep 17 00:00:00 2001 From: Markus Neusinger <2921697+MarkusNeusinger@users.noreply.github.com> Date: Thu, 15 Oct 2026 09:40:17 +0200 Subject: [PATCH 2/2] chore: add PR reference to the agents-md-bridge fragment Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GdMSqLR5ww4ji74EUSmk9M --- changelog.d/agents-md-bridge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/agents-md-bridge.md b/changelog.d/agents-md-bridge.md index 3e7c8310fc2..5043c7fe5ce 100644 --- a/changelog.d/agents-md-bridge.md +++ b/changelog.d/agents-md-bridge.md @@ -5,4 +5,4 @@ Antigravity CLI (`agy`), Codex, and other tools that read those paths load the same rules and skills from one source instead of a third file to keep in sync. A unit test fails if either link is replaced by a real file or points - elsewhere. + elsewhere. (#12187)