How to Create Cross-References Between Skills Using the @ Syntax

Use the bracketed syntax @[skills/<skill-id>] 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/<skill-id>] 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.

@<skill-id> 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 (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:

@[skills/<skill-id>]

• @ plus [ … ] tells the rendering system that this is a link, not an invocation.
• Inside the brackets you must use the canonical path skills/<skill-id> (the directory name containing the target 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 (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:

# 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:

## 🔗 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 (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 (lines 68-78) recommends cross-references specifically for delegating to sub-agents without workflow duplication:

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:

# Incorrect Usage

Use @database-design to load the skill immediately.  <!-- Triggers force-load! -->

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 (lines 68-78), agents access information only when needed, preserving context window space for active tasks.

Key implementation files include:

• skills/architecture/SKILL.md: Demonstrates the canonical @[skills/...] table syntax (lines 27-34)
• 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: Documents the token-efficiency rationale for cross-references (lines 68-78)

Summary

• Use @[skills/<skill-id>] 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 @<skill-id> 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 (lines 97-102). Always use @[skills/<skill-id>] 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/<skill-id> 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 (lines 27-34).

Why does the Architecture skill use backticks around cross-references in tables?

In 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}