Use `@AGENTS.md` reference in CLAUDE.md instead of symlink for Windows compatibility
- Dominant language
- Python
- Stars
- 993
- Forks
- 51
- Avg merge
- 7h 49m
- Merged PRs (30d)
- 2
Description
## Problem
The current skill recommendation in [`skills/agents-md/SKILL.md`](https://github.com/getsentry/skills/blob/main/skills/agents-md/SKILL.md) suggests:
> If a Claude-compatible entrypoint is required, symlink `CLAUDE.md` to `AGENTS.md`.
This approach has a critical issue on Windows: creating symlinks requires **UAC elevation** (admin privileges) by default. Without Developer Mode enabled or running as an administrator, the `mklink` command and most symlink APIs will fail with an access denied error. This makes the symlink approach a poor cross-platform recommendation.
## Suggested Fix
Claude Code officially supports importing other files via the `@filename` syntax inside `CLAUDE.md`. The recommended cross-platform approach is to create a `CLAUDE.md` that simply references `AGENTS.md`:
```markdown
@AGENTS.md
```
This is natively supported by Claude Code (see [anthropics/claude-code#6235](https://github.com/anthropics/claude-code/issues/6235)) and works on all platforms — including Windows — without any special permissions.
## Proposed Change
Update the skill guidance to replace the symlink recommendation with:
> If a Claude-compatible entrypoint is required, create a `CLAUDE.md` file containing `@AGENTS.md` to reference the shared file.
This is simpler, more portable, and aligns with Claude Code's own recommended approach for file composition.
Contributor guide
Research direction
Open skills/agents-md/SKILL.md and find the guidance recommending a symlink from CLAUDE.md to AGENTS.md. Replace that recommendation with creating CLAUDE.md containing @AGENTS.md, then review the surrounding Markdown for consistent wording and formatting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100