---
title: "Knowledge and skills: how AI agents use your business knowledge"
description: How does an AI agent use your team’s policies and ways of working? Learn how knowledge files and skills give an agent the context it needs, without putting everything into every request.
canonical_url: https://hubzoid.com/academy/inside-ai-agents/02-knowledge-and-skills
last_updated: 2026-10-14
---

# Knowledge and skills: how AI agents use your business knowledge

Give an agent the right knowledge and procedure for a task.

Lesson 2 of 9. Video length 3:15.

[Watch the video on YouTube](https://www.youtube.com/watch?v=rcJAZoZW83Y)

## Two kinds of files

|  | Knowledge | Skill |
| --- | --- | --- |
| Answers | What is true? | How do we do this? |
| Example | `returns-policy.md` | `daily-report.md` |
| The model loads it when | a question needs the fact | a task matches the procedure |
| Changes | when a policy or fact changes | when the way of working changes |

Both start with two lines of front matter. The `description` is what the model sees on its menu, so say what the file covers or when to use it.

## A knowledge file

```md title="knowledge/returns-policy.md"
---
name: returns-policy
description: Refunds, store credit and time limits.
---
# Returns policy

- Refunds within 30 days, with a receipt.
- Store credit up to 45 days.
- Damaged books: replace or refund, at any time.
- Gift receipts: store credit only.
- Special orders can't be returned unless damaged.
```

## A skill file

```md title="skills/daily-report.md"
---
name: daily-report
description: Write the morning report for Nora.
---
# Daily report

1. Sales by branch, from yesterday, compared with last week.
2. Titles running low: under 5 days of stock.
3. Anything unusual, first: a branch up or down by 20% or more.
4. Keep it to one screen, with the numbers in a table.
```

## How the model finds them

The model gets two small tools for each kind of file: one lists the menu, one reads a full file.

| Tool | Returns |
| --- | --- |
| `list_knowledge` | Every knowledge file as `name: description` |
| `read_knowledge(name)` | The full text of one knowledge file |
| `list_skills` | Every skill as `name: description` |
| `load_skill(name)` | The steps of one skill |

Claude and Codex handle skills the same way.

## Raw data is searched, not read

Large files, such as a year of sales, live in `raw_data/`. The agent searches them with `grep_data` and reads only the lines that match.

```csv title="raw_data/sales.csv (first lines)"
date,branch,title,copies
2026-09-13,Riverside,Paper Moons,2
2026-09-13,Riverside,Salt and Stars,2
2026-09-13,Riverside,All other titles,202
```

> **Warning: Keep secrets and prices out of knowledge**
>
> Everyone who can use the agent can read its knowledge. Discounts, purchase prices and passwords belong behind a restricted tool (lesson 5).

## Try it: write your first skill

1. **Pick one task you repeat every week,** such as chasing late supplier orders.
2. **Write it as five short steps,** one action each.
3. **Add the front matter:** a short `name` and a `description` that says when to use it.
4. **Save it as a Markdown file.** The template below is a working example.

```md title="my-first-skill.md"
---
name: weekly-supplier-follow-up
description: Use on Fridays to chase any supplier order that is late.
---
# Weekly supplier follow-up

1. List open orders older than 7 days.
2. Group them by supplier.
3. Check each against the promised delivery date.
4. Draft one short, polite email per late supplier.
5. Log what you sent, with the date.
```

In lesson 5, this file goes into a hub's `skills/` folder.

## If you're stuck

### Should this be knowledge or a skill?

What is true: knowledge. How we do it: a skill. A skill can point to a knowledge file, as the daily report does with the KPI definitions.

### The agent doesn't use my file

Check the `description`. "Returns rules" is vague. "Refunds, store credit and time limits" matches real questions. Then check the front matter sits between two `---` lines at the top.

### My document is very long

Split it by topic, one clear description each. Growing tables and logs go in `raw_data/`.

### I changed a file. When does the agent see it?

Knowledge edits apply on the next question. Skills load when the hub starts, so restart it after changing one.

## Go deeper

- [Hub file reference](https://hubzoid.com/docs/reference/hub-files): Every file a hub can hold, and its format.
- [Design an agent](https://hubzoid.com/docs/guides/design-an-agent): Decide what goes in instructions, knowledge and skills.
- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): How Claude loads skills on demand.
- [Codex skills](https://developers.openai.com/codex/skills): The same pattern in Codex.

## Transcript

### Intro (0:00)

Welcome back to Inside AI Agents. Last time, the harness, the loop that lets a model do real work. This time, what the model reads while it works.

### The shop's know-how (0:12)

Wren and Page has sold books for twenty years. Everything the shop knows lives in three places. A binder behind the counter. A shared drive. And people's heads.

The returns policy. What sell-through means. Which publisher gives which discount. How Maya checks an invoice. How Nora likes the morning numbers.

A model knows none of this. It knows books in general, not this shop.

You could paste it all into every request. But that's hundreds of pages, sent every single time. It's slow, it costs more, and the model gets less precise when it has to wade through everything.

### Two kinds of files (0:51)

So the shop's know-how is written down as two kinds of files.

Knowledge is what's true. The returns policy. What the numbers mean. The terms agreed with each publisher. Each document gets a name, and one line saying what it covers.

Skills are how the work is done. Check an invoice. Write the daily report. Each skill is a short procedure, step by step, with one line saying when to use it.

### A menu, not the whole binder (1:18)

Remember the menu from last time? This is where it comes from. The harness sends the model only the names and descriptions. A few lines, instead of hundreds of pages.

### Knowledge, when it's needed (1:29)

Now Sam, who runs the Riverside branch, has a question. A customer wants to return a book they bought five weeks ago. Can they?

The model scans the menu, and spots the returns policy. It asks to read it, and the harness hands back just that one document. Refunds within thirty days. Store credit up to sixty.

So the answer is store credit, and the model can say exactly where that came from.

### Skills, when they're needed (1:57)

Later, Nora asks for the morning report. That matches a skill. Write the daily report. The model loads it, and follows the steps. Sales by branch. Titles running low. Anything unusual, first. The same way every time, whoever asks.

### Too big to read (2:14)

Some things are too big to read at all. A year of sales. Every past invoice. Those stay as raw data. The model searches them, and reads only what matches.

And because it's all just files, the team keeps it current. Change the returns policy once, and every answer uses the new version.

### Knowledge and skills (2:33)

So that's how an agent learns a business. Knowledge says what is true. A skill says how to do something. And the harness loads each one only when it's needed.

Claude and Codex handle skills the same way. Names first, and the full steps only when they're needed.

Knowledge says what's true. Skills say how.

### Try it and next (2:54)

Try this. Pick one task you repeat every week. Write it down in five steps. Give it a name, and one line saying when to use it. That's a skill.

Next time, the brain gets its hands. Tools and connectors, and how an agent reaches your systems.

## What the video shows

- Knowledge is a reference document. A skill is a named procedure with steps.
- The menu gives the model short descriptions first. The full file is loaded only when needed.

## Files and further reading

- [Download First skill template](https://hubzoid.com/academy/examples/part-1/my-first-skill.md)
- [Hub file reference](https://hubzoid.com/docs/reference/hub-files)