# How to Create Cross-References Between Skills Using the @ Syntax > Learn how to create cross-references between skills using the @ syntax. Discover lightweight, clickable links that resolve at read-time without consuming tokens. - Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills) - Tags: how-to-guide - Published: 2026-03-18 --- **Use the bracketed syntax `@[skills/]` to create lightweight, clickable links between skills that resolve at read-time without consuming tokens or triggering automatic skill loading.** The `sickn33/antigravity-awesome-skills` repository implements a specialized markdown linking convention designed for token-constrained AI agents. Creating cross-references between skills using the @ syntax allows authors to reference related capabilities while keeping individual skills lightweight and performant. ## The Bracketed @ Syntax vs. Force-Loading In this codebase, the `@` symbol serves two distinct purposes depending on formatting. **`@[skills/]`** creates a passive cross-reference link. The brackets indicate to the rendering system that this is a navigation link, not an invocation command. The reference resolves at read-time, meaning the target skill remains unloaded until explicitly requested by a user. **`@`** without brackets triggers immediate skill loading. This force-load syntax consumes tokens immediately and violates the repository's cross-referencing guidelines when used for documentation purposes. According to the Writing-skills checklist in [`skills/writing-skills/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/SKILL.md) (lines 97-102), force-loading via `@` syntax is explicitly prohibited in cross-references to maintain token efficiency. ## Canonical Path Structure Every cross-reference must use the canonical path format: ```markdown @[skills/] ``` - `@` plus `[` … `]` tells the rendering system that this is a **link**, not an invocation. - Inside the brackets you must use the canonical path `skills/` (the directory name containing the target [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md)). - The link is resolved at *read-time* – the target skill is **not** force-loaded. The Architecture skill demonstrates this convention in [`skills/architecture/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/architecture/SKILL.md) (lines 27-34), using the syntax in its "Related Skills" table to link to complementary capabilities without bloating the current context. ## Practical Implementation Examples ### Basic In-Text References Embed cross-references naturally within skill documentation: ```markdown # Database Design Patterns This skill extends the concepts covered in @[skills/architecture]. For authentication implementations, see @[skills/auth-patterns]. ``` These render as clickable links to the respective skill pages without automatic loading. ### Related Skills Tables The canonical implementation appears in structured reference tables: ```markdown ## 🔗 Related Skills | Skill | Purpose | |-------|---------| | `@[skills/database-design]` | Schema design fundamentals | | `@[skills/deployment-procedures]` | Production deployment | | `@[skills/performance-tuning]` | Optimization strategies | ``` This pattern, established in [`skills/architecture/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/architecture/SKILL.md) (lines 27-34), provides quick navigation while keeping the current skill's token count minimal. ### CSO Guide Recommendations The CSO Guide in [`skills/writing-skills/references/cso/README.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/references/cso/README.md) (lines 68-78) recommends cross-references specifically for delegating to sub-agents without workflow duplication: ```markdown Use sub-agents for search operations. See @[skills/delegating-to-subagents] for detailed workflows. ``` ## Common Anti-Patterns to Avoid Avoid using the unbracketed `@` syntax in skill documentation: ```markdown # Incorrect Usage Use @database-design to load the skill immediately. ``` Replace with `@[skills/database-design]` to maintain the lightweight reference behavior required by the codebase standards. ## Token Efficiency and Source Files The CSO Guide explains that bracketed cross-references prevent workflow duplication while respecting token budgets. By referencing rather than inlining content from [`skills/writing-skills/references/cso/README.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/references/cso/README.md) (lines 68-78), agents access information only when needed, preserving context window space for active tasks. Key implementation files include: - [`skills/architecture/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/architecture/SKILL.md): Demonstrates the canonical `@[skills/...]` table syntax (lines 27-34) - [`skills/writing-skills/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/SKILL.md): Contains the explicit prohibition against `@` force-loading in cross-references (lines 97-102) - [`skills/writing-skills/references/cso/README.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/references/cso/README.md): Documents the token-efficiency rationale for cross-references (lines 68-78) ## Summary - Use `@[skills/]` for all cross-references between skills in the antigravity-awesome-skills repository - The bracketed syntax creates links resolved at read-time without loading target skills or consuming tokens - Canonical paths require the `skills/` prefix and match the target directory name exactly - Force-loading via bare `@` is prohibited in cross-references per the Writing-skills checklist - Reference implementations exist in the Architecture skill and CSO Guide documentation ## Frequently Asked Questions ### What happens if I use @skill-id without brackets? Using `@skill-id` without square brackets triggers immediate skill loading, consuming tokens and violating the Writing-skills checklist policy found in [`skills/writing-skills/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/writing-skills/SKILL.md) (lines 97-102). Always use `@[skills/]` to create passive links that don't execute until explicitly invoked by a user. ### Can I use relative paths or aliases instead of skills/? No, the system requires the canonical path `skills/` inside the brackets. The rendering system in `sickn33/antigravity-awesome-skills` expects this specific prefix to resolve links correctly within the repository structure, as demonstrated in [`skills/architecture/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/architecture/SKILL.md) (lines 27-34). ### Why does the Architecture skill use backticks around cross-references in tables? In [`skills/architecture/SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/architecture/SKILL.md) (lines 27-34), backticks wrap the bracketed syntax (`` `@[skills/...]` ``) to display the reference as code-formatted text within table cells while preserving the link functionality. This formatting improves readability in structured tables without breaking the cross-reference resolution. ### Do cross-references work in any markdown file or only SKILL.md files? While canonical examples appear in [`SKILL.md`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SKILL.md) files throughout the `skills/` directory, the linking convention applies to any documentation following the antigravity-awesome-skills format. The system resolves `@[skills/...]` references wherever they appear in the repository's markdown content, though the primary use case is linking between skill documentation.