Skip to main content
Mentions are the way skills reference other resources and skills in Better Skills. This guide covers all mention forms and when to use each.

​
Mention Syntax Overview

Better Skills uses three types of mention tokens:
  1. Draft mentions: [[resource:new:path]] — used when authoring local skill files
  2. Persisted mentions: [[resource:uuid]] or [[skill:uuid]] — used after resources are created
  3. Escaped mentions: \[[resource:...]] — prevents resolution when documenting syntax

​
Draft Mentions

Use draft mentions when creating or editing skills locally.

​
Syntax

[[resource:new:references/guide.md]]
[[resource:new:scripts/setup.ts]]
[[resource:new:assets/template.html]]

​
Rules

  • Path is relative to the skill root
  • Use forward slashes regardless of OS
  • No leading ./ or absolute paths
  • CLI resolves these to UUID-based mentions on create or update

​
Example

---
name: my-skill
description: Example skill demonstrating mention syntax
---

# My Skill

## Workflows

For deployment steps, see [[resource:new:references/deployment.md]].

Use the validation script: [[resource:new:scripts/validate.ts]]

## Templates

Boilerplate template: [[resource:new:assets/template.tsx]]

​
Persisted Mentions

After creating or updating a skill, draft mentions are resolved to UUID-based persisted mentions.

​
Resource Mentions

Link to an existing resource by UUID: 
[[resource:550e8400-e29b-41d4-a716-446655440000]]
You typically don’t write these manually — the CLI generates them during create or update.

​
Skill Mentions

Link to another skill in your vault: 
[[skill:7c9e6679-7425-40de-944b-e07fc1f90ae7]]
Use skill mentions to create cross-references between related skills. Cross-skill links help agents discover related skills contextually.
1

Find Related Skills

List all vault skills to identify potential links:
better-skills list --all
Note the UUID of any related skill.
2

Add Inline Mentions

Add [[skill:uuid]] mentions where contextually relevant — not in a generic “Related Skills” section.
Good: inline in the section where the context is relevant
## React Integration

When writing React components that use atoms, also consult
[[skill:uuid]] for render and bundle performance patterns.
Bad: a catch-all list at the end of SKILL.md
## Related Skills

- [[skill:uuid]]
- [[skill:uuid]]
3

Mentions in Reference Files

Skill mentions can also go in reference files (not just SKILL.md):
# API Integration Patterns

For authentication flows, see [[skill:auth-uuid]].
This loads just-in-time when the agent reads that reference.

​
Escaping Mentions

Prefix mentions with a backslash to prevent resolution: 
\[[resource:new:path/to/file]]
\[[resource:uuid]]
\[[skill:uuid]]
Use escaping when documenting or explaining mention syntax itself. The backslash is stripped in rendered output, so readers see the literal form.

​
Example

In documentation explaining mention syntax: 
# Mention Syntax Guide

To reference a resource file, use:

\[[resource:new:references/guide.md]]

After creation, this becomes:

\[[resource:550e8400-e29b-41d4-a716-446655440000]]
Without escaping, Better Skills would attempt to resolve these as actual links.

​
Auto-Linking Behavior

Better Skills automatically manages graph links based on mentions.

​
How It Works

  1. When you create or update a skill, the CLI parses all mentions in:
    • SKILL.md
    • All resource markdown files (.md, .mdx, .txt)
  2. For each mention found:
    • Validates the target exists and belongs to the same vault
    • Creates an auto-generated link in the skill graph
    • Tags the link with metadata.origin = "markdown-auto"
  3. On subsequent updates:
    • Deletes old auto links for changed sources
    • Recreates links based on current mention content
    • Preserves manually created links

​
Same-Vault Constraint

Mentions can only reference targets in the same vault:
Valid: skill and mentioned resource both in “my-vault”
Invalid: skill in “my-vault” trying to mention resource in “other-vault”
This ensures vault boundaries are respected and prevents accidental cross-vault dependencies.

​
Validation Rules

Before creating or updating a skill, better-skills validate checks mention integrity.

​
Validation Checks

  1. Mention syntax: All mentions use correct format
  2. Target existence: Every [[resource:new:...]] path points to an existing file
  3. Resource coverage: Every file in references/, scripts/, or assets/ has at least one inbound mention
  4. No orphans: No mentions point to non-existent files

​
Example Errors

$ better-skills validate ./my-skill

✗ validation failed

error: resource file has no mentions
file: references/orphaned-guide.md
fix: add [[resource:new:references/orphaned-guide.md]] in SKILL.md or another resource

error: mention target not found
mention: [[resource:new:references/missing.md]]
fix: create the file or remove the mention
Validation warnings are treated as failures. Fix all issues before running create or update.

​
Bulk Rewrite

When importing skills from external sources, use rewrite-links to convert local links to mentions.

​
Command

better-skills rewrite-links <dir> [--dry-run]

​
What It Does

  • Scans SKILL.md and markdown resources
  • Converts common link formats to [[resource:new:...]] mentions:
    • Markdown links: [text](references/foo.md)
    • Wiki links: [[references/foo.md]]
    • Autolinks: <references/foo.md>
    • Bare paths: references/foo.md (context-dependent)
  • Skips fenced code blocks, inline code, and escaped mentions

​
Example

# Dry run to preview changes
better-skills rewrite-links ./imported-skill --dry-run

# Apply changes
better-skills rewrite-links ./imported-skill

# Validate after rewrite
better-skills validate ./imported-skill
rewrite-links catches most link patterns but may miss edge cases. Always run validate after rewriting and manually fix any remaining bare links.

​
Examples from Workflows

​
Creating a New Skill

---
name: api-client
description: HTTP client utilities for REST APIs
---

# API Client Skill

## Configuration

For setup instructions, see [[resource:new:references/setup.md]].

## Usage Examples

Authentication flow: [[resource:new:references/auth-flow.md]]

Error handling: [[resource:new:references/error-handling.md]]

## Scripts

Generate client code: [[resource:new:scripts/generate-client.ts]]

​
Importing from GitHub

After cloning a skill repository: 
git clone --depth 1 https://github.com/org/skill-repo.git ./skill-repo

# Rewrite local links to mention syntax
better-skills rewrite-links ./skill-repo

# Validate
better-skills validate ./skill-repo

# Create
better-skills create --from ./skill-repo

​
Updating with New Resources

# Clone existing skill
better-skills clone my-skill --to ./my-skill

# Add new reference file
cat > ./my-skill/references/new-guide.md << 'EOF'
# New Guide

Content here...
EOF

# Add mention in SKILL.md
echo "\n## New Section\n\nSee [[resource:new:references/new-guide.md]]" >> ./my-skill/SKILL.md

# Validate and update
better-skills validate ./my-skill
better-skills update my-skill --from ./my-skill

​
Next Steps

Creating Skills

Learn how to create new skills with proper mention structure

Skill Resources

Understand resource types and organization

Build docs developers (and LLMs) love

Get started for freeTalk to us