Conversation
Adds the AGENTS.md open-standard file for AI coding agents (agents.md). Every claim evidence-backed against Makefile, package.json, source tree, or equivalent manifest. Zero fabrication.
| </content> | ||
| </invoke> No newline at end of file |
There was a problem hiding this comment.
I assume an agent generated this, but since there are no opening tags, we can probably remove these
|
looks like there is also a |
Per review feedback on the sibling atree PR (onflow/atree#658), reference the CODEOWNERS file rather than listing its members inline. The hard-coded list would silently go stale when the team rotates reviewers, since GitHub enforces CODEOWNERS but nothing enforces AGENTS.md. Matches the pattern the surrounding bullets already use for codecov.yml, SECURITY.md, CONTRIBUTING.md, etc.
Per @peterargue's review on PR #33, merge the two agent-facing files into a single source of truth to avoid drift. AGENTS.md is now the canonical file; CLAUDE.md is a symlink back to it, so any tooling still looking for CLAUDE.md (including early Claude Code versions) finds the same content. Content merged from CLAUDE.md into AGENTS.md: - "How Skills Work" — three-level progressive disclosure - "Skill Routing Guide" — developer-intent → skill table - "Content Sources" — cadence-rules / flow-cli / Flow docs The agents.md standard explicitly documents the symlink migration path. AGENTS.md is natively supported by Claude Code, Codex, Cursor, Copilot, Windsurf, and Gemini CLI — so making it the source of truth expands tool coverage without losing anything.
|
Good call — done in de7f586. Merged CLAUDE.md's unique sections ("How Skills Work", the skill routing table, and content sources) into AGENTS.md, then replaced CLAUDE.md with a symlink pointing to AGENTS.md. Single source of truth; backwards-compatible with anything still checking for CLAUDE.md. |
Verification pass caught that cadence-testing was missing from the skills table, even though it exists in plugins/flow-dev/skills/ and is referenced by the Skill Routing Guide. Source-of-truth check: $ ls plugins/flow-dev/skills/ cadence-audit cadence-testing flow-dev-setup flow-react-sdk cadence-lang cadence-tokens flow-cli flow-tokenomics cadence-scaffold flow-defi flow-project-setup That's 11 skills. cadence-testing has 6 reference files under plugins/flow-dev/skills/cadence-testing/references/. Updates: - Overview copy: "ten skills" → "eleven skills" - Skills table: add cadence-testing | 6 row
The existing AGENTS.md is a strict superset of CLAUDE.md — every command, architecture note, and convention in CLAUDE.md is already covered in AGENTS.md, usually in more detail (16 make targets vs ~5, full feature package list, 11 gotchas vs 6 generic conventions, plus a Files Not to Modify section CLAUDE.md lacks). Rather than maintain two files that will drift, symlink CLAUDE.md to AGENTS.md. The agents.md standard explicitly documents this migration pattern. AGENTS.md is natively supported by Claude Code, Codex, Cursor, Copilot, Windsurf, and Gemini CLI — so making it the source of truth expands tool coverage without losing anything, and the symlink keeps any tooling still hardcoded to look for CLAUDE.md working unchanged. Same pattern applied on onflow/flow-ai-tools#33 per @peterargue's review.
|
Following the same pattern here: onflow/flow-cli#2338 |
There was a problem hiding this comment.
I was thinking of creating a symbolic link like
ln -s AGENTS.md CLAUDE.mdhowever, doing it this way is also fine. If you use @filename the agent will automatically load the file. otherwise I think it decides whether or not, so it may be less reliable
| @AGENTS.md |
There was a problem hiding this comment.
Good call — applied in fabe499. Replaced the symlink with a plain-text CLAUDE.md containing @AGENTS.md so Claude Code imports it explicitly rather than relying on symlink-following heuristics. Propagated the same change to the sibling PR on onflow/flow-cli#2338 where we'd also used the symlink pattern.
Per @peterargue's follow-up on PR #33: replace the CLAUDE.md → AGENTS.md symlink with a plain-text CLAUDE.md whose single line is the @AGENTS.md import directive. Claude Code treats @filename as an explicit import that guarantees the referenced file is loaded into context, whereas symlink following is heuristic and may not fire in every session. The @import approach also avoids Windows / non-Unix filesystem compatibility issues where symlinks degrade to plain-text files containing the target path. Functionally equivalent outcome for every other AGENTS.md-adopting tool (Codex, Cursor, Copilot, Windsurf, Gemini CLI), since they all read AGENTS.md directly.
2 participants
Summary
Adds
AGENTS.md— the open standard (agents.md, Linux-Foundation-backed, adopted by 60K+ repos) that guides AI coding agents (Claude Code, Codex, Cursor, Copilot, Windsurf, Gemini CLI) on a per-repo basis.How this file was generated
Authored via an evidence-based generator skill with a strict verify-before-claim protocol:
Makefile/package.json/ equivalentGlob/Readgo.mod/package.json/foundry.toml/ etc.What AGENTS.md contains
Test plan