Skip to main content
Resources are supplementary files that provide context, tools, or templates to skills. This guide covers resource types, naming conventions, and how to organize them.

​
Resource Types

Better Skills recognizes four resource categories based on folder location:

​
References

Contextual documentation loaded just-in-time when an agent needs detailed information. Location: references/ Examples:
  • API schemas and data models
  • Step-by-step workflows
  • Cheatsheets and quick references
  • Configuration examples
my-skill/
├── SKILL.md
└── references/
    ├── api-schema.md
    ├── deployment-workflow.md
    └── config-examples.yaml

​
Scripts

Executable code designed as tiny single-purpose CLIs. Use scripts to offload fragile or repetitive operations. Location: scripts/ Guidelines:
  • Keep scripts deterministic and focused
  • Return descriptive error messages on stderr so agents can self-correct
  • Do not bundle library code
Examples:
  • Validation utilities
  • Code generators
  • File transformers
my-skill/
├── SKILL.md
└── scripts/
    ├── validate-config.ts
    └── generate-boilerplate.sh

​
Assets

Templates or static files used in output. Assets are not intended for context loading. Location: assets/ Examples:
  • Boilerplate templates
  • Configuration file templates
  • Static output files
my-skill/
├── SKILL.md
└── assets/
    ├── component-template.tsx
    └── config-template.json

​
Other

Any other files in the skill root or custom folders. Use sparingly to keep the structure clean.

​
Adding Resources to Skills

Every resource file must be referenced using mention syntax.

​
Draft Mention Syntax

When creating or editing skills locally, use [[resource:new:path]] mentions: 
## Workflows

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

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

Template available at [[resource:new:assets/template.tsx]]
The CLI resolves these to UUID-based mentions during create or update.

​
Mention Requirements

Every file under references/, scripts/, or assets/ MUST have at least one mention — either in SKILL.md or in another resource file.
better-skills validate fails when any resource file lacks a mention reference.

​
Path Conventions

​
Relative Paths

Always use relative paths with forward slashes: 
[[resource:new:references/guide.md]]        ✓ Correct
[[resource:new:./references/guide.md]]      ✗ Avoid leading ./
[[resource:new:references\guide.md]]        ✗ No backslashes
/references/guide.md                        ✗ No absolute paths

​
Flat Structure

Prefer flat folder structures: 
references/
├── api-schema.md
├── deployment.md
└── config.md

references/
└── api/
    └── v1/
        └── schema.md    # Too nested
Nesting is acceptable when grouping many related files, but keep it minimal.

​
Resource Content and Metadata

​
Markdown Resources

Markdown files (.md, .mdx, .txt) can contain mentions to other resources or skills: 
# Deployment Workflow

Before deploying, validate the configuration:

[[resource:new:scripts/validate-config.ts]]

For API schema details, see [[resource:new:references/api-schema.md]]

Related skill: [[skill:uuid-of-related-skill]]

​
Non-Markdown Resources

Scripts and assets are not automatically processed for mention resolution. If you need to document mention syntax in code examples, escape them: 
// Example script with literal mention in comment
// See \[[resource:new:references/api-schema.md]] for schema

​
References Folder Structure

The references/ folder is where most skill documentation lives. Organize it for progressive disclosure:

​
Example Structure

react-components/
├── SKILL.md                          # High-level routing
└── references/
    ├── component-structure.md        # How to structure components
    ├── styling-guide.md              # Tailwind CSS patterns
    ├── testing-workflow.md           # Component testing steps
    └── api-integration.md            # Data fetching patterns

​
Best Practices

  1. One concept per file: Keep reference files focused on a single topic
  2. Clear naming: Use descriptive filenames that indicate content
  3. Progressive loading: Don’t load all references by default — let SKILL.md route to them
  4. Cross-reference: Use mentions to link related reference files

​
Resource Update Behavior

When updating skills, the local folder is the desired state:
  • Added file locally → creates new resource remotely
  • Modified file locally → updates existing resource remotely
  • Deleted file locally → removes resource remotely
  • Renamed file → treated as delete old + create new

​
Example Update Flow

1

Clone Existing Skill

better-skills clone my-skill --to ./my-skill
2

Edit Local Resources

Add, modify, or delete files in references/, scripts/, or assets/.If adding a new file, add a mention in SKILL.md or another resource:
[[resource:new:references/new-guide.md]]
3

Validate Changes

better-skills validate ./my-skill
4

Update Remote Skill

better-skills update my-skill --from ./my-skill
The CLI diffs local resources against the server and applies changes.

​
Validation Rules

Before creating or updating a skill, better-skills validate checks:
  1. Frontmatter exists and has required name and description fields
  2. Name matches folder name exactly (case-sensitive)
  3. Every resource file under references/, scripts/, or assets/ has at least one mention
  4. Mention targets exist as files in the skill folder
  5. No orphaned mentions pointing to non-existent files
Validation warnings are treated as failures. Fix all issues before running create or update.

​
Next Steps

Markdown Mentions

Learn mention syntax for linking resources and skills

Creating Skills

Go back to the skill creation guide

Build docs developers (and LLMs) love

Get started for freeTalk to us