docs: add AI guidance files (AGENTS.md, CLAUDE.md, Skills)

[Rodriguespn]

What kind of change does this PR introduce?

Documentation — Introduces standardized AI guidance files to help AI coding agents work effectively on this codebase.

What is the current behavior?

AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) have no project-specific context when working on this repository, that could lead to:

• Running pnpm build during development instead of pnpm dev
• Editing auto-generated files (types.ts, server.json) that should never be modified manually
• Missing environment variables for tests
• Inconsistent code patterns

What is the new behavior?

This PR adds a layered system of AI guidance files:

File Type	Purpose
CLAUDE.md	Entry point that links to AGENTS.md
AGENTS.md	Commands, setup, code style, "Do NOT" warnings
Agent Skills	On-demand detailed patterns (testing, architecture, tool registration)

Hierarchy:

1. CLAUDE.md (root + packages) — Links to AGENTS.md

2. Root AGENTS.md — Repo-wide basics: monorepo structure, build/test commands, package manager, dev dependencies. Points to package-specific guides.

3. Package AGENTS.md — Package-specific commands, environment variables, code style, "Do NOT" warnings. References Skills for detailed patterns.

4. Agent Skills (.claude/skills/) — On-demand loading of detailed architecture, testing patterns, and tool registration guides. Only loaded when triggered by relevant tasks (Agent Skills docs).

Files added:

• AGENTS.md and CLAUDE.md at root and package levels
• Agent Skills in .claude/skills/ directories

Note on Agent Skills

The Agent Skills in this PR are Claude-specific. While an open standard for agent skills has been proposed, it is not yet stable:

• OpenAI Codex Skills — Experimental feature
• Cursor Skills — Only available in nightly builds

Once agent skills are officially adopted as an industry standard, we can adapt these files accordingly. This provides a good starting foundation.

References

• Using CLAUDE.md Files — Anthropic blog post
• Claude Code Best Practices — Anthropic engineering guide
• AGENTS.md Specification — Industry-standard format for AI agent guidance
• Agent Skills Overview — On-demand skill loading

[mattrossman]

These CLAUDE.md can be symlinks to AGENTS.md to save the extra lookup (inspired by the agent setup guide from https://www.effect.solutions/quick-start)

[Rodriguespn]

I guess they did the other way around and linked their Agents.md to Claude.md 😆 Good suggestion to use symlinks, it is more straight forward