Reference Files

By the Syncfusion DevTutorials team · Last updated October 22, 2026

What to move into a skill's references folder, how to split big guides into topic files, and how to write clear pointers that open each file only when a task needs it.

Keep the Detail Nearby, Not in the Way

A reference file is an extra file in a skill's references/ folder. It holds detail the skill needs only for some tasks. In this lesson, you will learn what to move into reference files, and how to tell the agent when to open each one.

A skill often needs a lot of team detail.

For example:

• the design tokens
• the accessibility checklist
• the API naming rules
• the security checklist

If all of it sits in SKILL.md, the agent reads all of it on every run.

Most runs need only a small part.

Simple lesson: keep the steps in SKILL.md. Move detail that only some tasks need into references/. Then point to it from the right step.

A Real-World Example

A senior developer does not memorise the whole design system.

They know where to look.

When a change touches colors, they open the color page. When it touches a login form, they open the security page.

A skill with reference files works the same way.

Click the button and open the Library tab.

• On the left: ui-review has two reference files and one script.
• In SKILL.md: steps 2 and 3 each name one reference file.

Simple lesson: a reference file is just a Markdown file. A step in SKILL.md says when to read it.

What You Will Learn

In this lesson, you will learn:

1. What belongs in references/, and what does not.
2. How to split a big guide into small topic files.
3. How to write a clear pointer to a reference file.
4. How to keep reference files healthy.

What Goes in references/

Put detail in references/ when only some tasks need it.

Good reference content:

• UI: design tokens, an accessibility checklist, rules for loading and empty screens.
• Backend: API naming, status codes, error format, paging rules.
• Security: a short OWASP list, rules for secrets.
• Testing: test naming rules, which test type covers what.

Keep these out of references/:

• Steps for every run. They belong in SKILL.md, because every run needs them.
• Exact rules a computer can check. They belong in scripts/. You learn this in the next lesson.
• Facts that change every week, like who is on call. They go stale. Use a tool for them.

Watch the token table move out of ui-review:

The table did not disappear. It now waits in its own file until step 2 needs it.

Simple lesson: ask "does every run need this?" If not, it is a reference file.

One Topic per File

A big reference file has the same problem as a big SKILL.md.

The agent opens it for one rule. Then it reads every other rule too.

So split a big guide by topic.

Example: one API guide becomes four small files.

api-endpoint/
  SKILL.md
  references/
    api/naming.md
    api/status-codes.md
    api/errors.md
    api/pagination.md

Now a task about paging opens only pagination.md.

For a very long topic, use two layers:

• Summary file: one line per rule. Opened on every security review.
• Detail file: examples and fixes for one rule. Opened only when that rule is broken.

Simple lesson: small files with clear names let each task read only what it needs.

Point to Each File Clearly

A pointer = a line in SKILL.md that names a reference file.

A good pointer has three parts:

• A condition: when to open the file.
• One file: the exact path.
• The right place: inside the step where it is needed.

Weak pointers:

• "See references/ for design rules."
• "Read the API guide."

Clear pointers:

• "If colors or spacing are used, compare them with references/design-tokens.md."
• "For list endpoints, follow references/api/pagination.md."

The agent reads the steps in order. So a pointer in step 2 is used at step 2.

Watch three requests reach ui-review:

Each request opened only the file its condition matched. The empty-state request opened nothing, because no file covers it yet.

Click the button and open the Activate tab.

• ui-review fires: its SKILL.md is read.
• The meter: tick only the files this request needs. Then tick them all and compare.

Now compare a weak pointer and a clear one:

The clear pointer says when, and names one file. So the agent knows what to do.

Simple lesson: write each pointer as a small rule: "If this, open that file."

Many Reference Files

Some skills have many reference files.

Then add one index file: references/index.md.

SKILL.md points to the index once. The index lists each topic and its file.

# References index

Open only the file you need:
- Colors, spacing, radius: references/design-tokens.md
- Labels, contrast, keyboard: references/wcag-checklist.md
- Loading, empty, error states: references/ux-states.md

Simple lesson: an index is a table of contents. It helps the agent pick the right file.

Keep References Healthy

Skills change over time. Two problems often appear:

• Orphan file = a file that no step mentions. The agent never opens it.
• Broken pointer = a step names a file that is not there anymore.

The Library checker warns about orphan files.

Click the button and try the whole loop on ui-review:

1. Type references/ux-states.md in the path box. Press + Add file.
2. Write three short rules for loading, empty and error screens. Press Save.
3. Look at the checker. It warns that the new file is never mentioned.
4. Open SKILL.md. Change step 4 so it names the new file with a condition. Press Save.

The warning goes away.

Simple lesson: after every change, check for orphan files and broken pointers.

TL;DR

1. Reference file = a file in references/ with detail only some tasks need.

2. Keep in SKILL.md:

   • steps, output format and final checks

3. Move to references/:

   • tokens, checklists, API rules, security lists

4. Keep out of the skill:

   • exact checks → scripts/
   • facts that change every week → a tool
5. One topic per file. Use a summary and a detail file for long topics.
6. Pointer = condition + one file + inside the right step.
7. Many files? Add references/index.md.
8. Fix orphan files and broken pointers after each change.

Common Mistakes

Check Your Understanding

Exercises

These exercises use the real ui-review skill.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• references/ holds detail that only some tasks need.
• Steps for every run stay in SKILL.md.
• Split big guides into small topic files.
• Each pointer has a condition, one file, and sits in its step.
• Add an index when a skill has many reference files.
• Check for orphan files and broken pointers.
• Never put secrets or unread text in references/.

Next: Scripts and Validators. You will turn exact rules into small programs the agent can run.