The contents page

About this video

Say your agent keeps needing seven documents: a brand guide, a proposal checklist, the procedure for the monthly report and more. You could paste them all into the instruction file, but that's about fifty pages, some thirty thousand tokens, sent in every request, and most days almost none of it is needed.

Think of a big reference book. You don't read it cover to cover before every task: you read the contents page, find the chapter you need, and read only that. A skill gives an agent the same thing. A skill is a folder that teaches an agent one procedure. At its heart is a file called SKILL.md: a header with a name and a description of what the skill does and when to use it, then the procedure as clear steps. The folder can hold extra files the steps refer to, like a reference sheet or a small script. In Claude Code skills live in a project's .claude/skills/ folder or your own ~/.claude/skills/, and you can start one yourself by typing a slash and its name.

The trick is when each part reaches the context, which is called progressive disclosure. Always: only each skill's name and description. When a task matches one: the whole SKILL.md, which the agent then follows. Only if a step needs them: the extra files, one at a time, and a script is simply run, so the agent sees its result without reading its code. Twenty skills pasted in whole might cost a hundred thousand tokens; their descriptions alone, a couple of thousand.

When the agent is choosing, the description is all it has seen, so "Brand stuff." means the skill is never used. Say what it does and the words people use when they need it. Short facts every session needs belong in the instruction file; a procedure needed only sometimes is a skill. This video explains the agent skill on Knaph.

Transcript

1. 0:00Your agent keeps needing seven documents: a brand guide, a proposal checklist, a report procedure, and more.
2. 0:07Why not paste them all into the instruction file?
3. 0:10That's about fifty pages. Some thirty thousand tokens, in every request.
4. 0:15And most days, almost none of it is needed.
5. 0:20Think of a big reference book.
6. 0:23You don't read it cover to cover before every task.
7. 0:27You read the contents page, find the chapter you need, and read only that.
8. 0:33A skill gives an agent the same thing.
9. 0:40A skill is a folder that teaches an agent one procedure.
10. 0:45At its heart is a file called SKILL.md.
11. 0:49At the top, a header: its name, and a description of what it does and when to use it.
12. 0:56Below, the procedure itself, in clear steps, plus any extra files.
13. 1:00You can also start one yourself, with a slash.
14. 1:04The trick is when each part reaches the context.
15. 1:08Always: only each skill's name and description.
16. 1:12When a task matches one, the agent reads that whole SKILL.md, and follows it.
17. 1:18Only if a step needs them, it opens the extra files, one at a time.
18. 1:24A script is simply run. The agent sees its result, never its code.
19. 1:29This is called progressive disclosure.
20. 1:32So what does it save?
21. 1:35Twenty skills pasted in whole might be a hundred thousand tokens.
22. 1:40Their descriptions alone: a couple of thousand.
23. 1:44The agent knows many procedures, and pays only for the ones it uses.
24. 1:52But when it's choosing, the description is all it has seen.
25. 1:57Brand stuff. That tells it nothing. The skill is never used.
26. 2:02Checks a document against the brand guide. Use before anything is sent to a client.
27. 2:08Say what it does, and the words people use when they need it.
28. 2:14So, instruction file or skill?
29. 2:17Short facts every session needs go in the instruction file.
30. 2:21A procedure needed only sometimes becomes a skill.
31. 2:25A good test: if most sessions would never use it, it's a skill.
32. 2:34Carry the description. Open the rest when it's needed.