getsentry / getsentry/skills

Use `@AGENTS.md` reference in CLAUDE.md instead of symlink for Windows compatibility

Open Beginner friendly
#168 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.