[DOCS] SKILL.md @-imports work but are undocumented — docs imply the feature doesn't exist

Documentation Type

Incorrect/outdated documentation

Documentation Location

docs.anthropic.com/en/docs/claude-code/skills

Section/Topic

SKILL.md file format — supported features

Current Documentation

The skills documentation lists the supported mechanisms for SKILL.md as: frontmatter configuration, !command dynamic context injection, argument substitution, and supporting files in the skill directory. @path imports are not mentioned. The documentation assistant trained on this content explicitly states: "@-import is not supported in SKILL.md files."

What's Wrong or Missing?

@path imports are in fact supported in SKILL.md and behave identically to how they work in CLAUDE.md: the referenced file's content is fully inlined at skill invocation time, with paths resolved relative to the project root. The omission from the docs causes the documentation assistant to actively deny the feature exists, meaning authors who consult the docs will never discover it.

Suggested Improvement

Add a section (or a note alongside the existing @-import documentation for CLAUDE.md) confirming that @path imports are supported in SKILL.md, with: path resolution behaviour (relative to project root), invocation-time inlining semantics, and a brief example — e.g. a _shared/ folder containing a reusable instruction block imported by multiple skills.

Impact

Medium - Makes feature difficult to understand

Additional Context

Discovered empirically while building a shared-trait system for skill composition. A test skill containing @.claude/skills/_shared/test.md was invoked; the imported content was confirmed present in the skill instructions. This enables a PHP-trait-style pattern: common instruction blocks (e.g. database connection setup, GitLab API access) maintained in one place and imported by any skill that needs them, rather than copy-pasted into each one.

(Human here, adding a single comment to all of the above: Claude wrote the entry, so I trust it to be meaningful to you)