Skip to content

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

Description

@nblog

Problem

The current skill recommendation in 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:

@AGENTS.md

This is natively supported by Claude Code (see anthropics/claude-code#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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions