A plain-English guide to context windows, Skills files, and a small but powerful change — called front matter — that makes your AI coding tool faster and smarter.
Claude Code uses a thing called a context window — think of it as a desk where Claude can only spread out a limited number of papers at once. When that desk gets full, old information gets pushed off the edge.
Skills files are instruction playbooks that tell Claude how to do specific jobs — like committing code or reviewing a pull request. Before a recent update, Claude had to read every playbook in full just to figure out which one was relevant. That wasted precious desk space.
The fix was front matter — a short header at the top of each Skills file, like a label on the spine of a binder. Now Claude reads only the label first, figures out which playbook it actually needs, and only then opens the full thing. The desk stays cleaner, Claude has more room to think, and your work moves faster.
Here's the thing about AI tools: most of what makes them feel "smart" or "slow" or "forgetful" comes down to something you can't see — how efficiently the AI manages the information it's working with at any given moment.
You don't have to understand this to use Claude. But if you've ever noticed Claude seeming to forget earlier parts of a conversation, or if you've wondered why some responses feel snappier than others — this is the explanation. And understanding it will help you get more out of every session.
The change described in this tutorial — adding front matter to Skills files — is a great example of a principle that runs through all of software engineering: you don't have to load everything at once. Reading the label before opening the box is always faster than opening every box to find the one you need. This tutorial will show you exactly why.
Not long ago, understanding an AI tool's internals required a computer science background. That world no longer exists. If you can understand what a desk looks like when it's buried in papers, you can understand context windows. Let's start there.
Before we talk about Skills files or front matter, we need to understand the most important concept in AI tools: the context window.
Imagine a physical desk. You can spread papers across it, open books, lay out notes, and work with all of it at once — as long as it all fits on the surface. But the desk has a fixed size. If you pile on too much, the oldest papers start sliding off the back edge to make room for new ones. Anything that falls off the desk is gone. You can't glance back at it. It's simply no longer in front of you.
That's a context window. When you're working with Claude, everything in your current session — your messages, Claude's replies, any files or instructions it's been given — is laid out on that metaphorical desk. Claude can work with all of it simultaneously. But the desk has a hard limit on how much can fit.
When that limit is reached, older content gets dropped to make room for new content. This is why, in very long conversations, an AI might seem to "forget" something you mentioned at the start — it literally no longer has access to it. That information slid off the back of the desk.
The size of a context window is measured in tokens — roughly pieces of words. "Context" is about one token. "Contextual" is two. A typical conversation message might be 100–400 tokens. This guide you're reading right now would be several thousand tokens.
Even though modern context windows can hold hundreds of thousands of tokens, that limit is real. Every piece of information loaded into context — instructions, files, conversation history, code — takes up space. Efficient tools load only what's needed.
When the context window has breathing room, Claude can hold more of your conversation in view, reason more carefully, and keep track of more nuance. A crowded context window is like trying to think at a buried desk.
A common misconception: "the AI is getting dumber over time." Usually, what's actually happening is that older context is being pushed out as the conversation grows longer. The model itself hasn't changed — the desk just got full. The fix is starting a fresh conversation, or loading fewer things into context upfront.
Now that you understand the desk, let's talk about what gets piled onto it. In Claude Code, there's a feature called Skills files.
Imagine a binder full of laminated instruction cards sitting on a shelf next to your desk. Each card is a playbook for a specific job: one card explains how to commit code properly, another explains how to review a pull request, another explains how to write documentation in the team's style. When you need to do one of those jobs, you pull the right card, bring it to your desk, and follow the instructions.
That's a Skills file. It's a document that tells Claude how to do a specific, repeatable task — and it's separate from the conversation itself. You or your team write these playbooks once, save them as files, and Claude loads them whenever they're relevant.
This is enormously useful. Instead of re-explaining "here's how we commit code on this project" at the start of every session, you write it once in a Skills file and Claude knows it every time. It's the difference between briefing a new contractor every day versus having a trained team member who already knows the procedures.
Plain instructions in plain language. "When asked to commit code, always write a message in present tense. Always include a Co-Authored-By line." Claude reads these and follows them.
A real project might have Skills files for: committing code, reviewing PRs, writing tests, generating documentation, handling database migrations, and more. Each is its own file with its own instructions.
Write the playbook once. Every conversation after that benefits automatically — without you having to re-explain anything. This is one of the biggest productivity gains in Claude Code.
Before Skills files, every conversation started from scratch. You had to remind Claude of your team's preferences, your project's conventions, your coding style — every single session. Skills files solved that problem by making expertise persistent. But they introduced a new problem, which we're about to get to.
Here's where it gets interesting. We've established that Skills files are like laminated instruction cards in a binder. Now let's talk about front matter — and to understand it, we need to think about how you'd use that binder.
Imagine a recipe binder with fifty recipe cards inside. You're making pasta tonight. Without any organization, you'd have to pull out each card, read through it, and figure out whether it's the pasta recipe or the soup recipe or the cake recipe. That takes time and effort — you're reading the full recipe just to discover it's the wrong one.
Now imagine each card has a small label in the top corner: PASTA · 30 min · stovetop. You can flip through the binder reading only the labels, find the right card in seconds, and only then read the full instructions. The label is the front matter.
In a Skills file, front matter is a short block of metadata placed at the very top of the file — before the actual instructions. It tells Claude the most important facts about this file at a glance: what this skill is called, what kind of task it handles, when it's relevant.
--- name: commit # ← the label: "this is the commit skill" description: Use when committing code # ← when Claude should use this triggers: ["commit", "git commit"] # ← keywords that activate this skill --- # the full instructions start here, after the front matter When committing code, always write the commit message in present tense. Include a Co-Authored-By line at the bottom. Check for any debug logs before committing...
---) mark the beginning and end of the front matter block. Everything between them is metadata. Everything after the second --- is the actual content of the file.
The front matter format shown above is called YAML front matter (YAML is just a simple way of writing key-value pairs, like a labeled form). You'll see this same pattern in many other tools — blog posts, documentation systems, configuration files. It's a widely-used convention: put the summary at the top, the full content below.
Front matter — A block of metadata at the top of a file, separated from the main content by three dashes (---). It describes the file without you having to read the full file. Think of it as the label on the outside of an envelope.
YAML — A simple human-readable format for writing structured data. name: commit is YAML. It's just "key: value" pairs, one per line.
Now we can put it all together. Let's look at what Claude actually had to do before front matter existed — and what it does now.
When you asked Claude to do a task, it would load every Skills file into the context window in full — all of them, completely — just to figure out which ones were relevant to your request.
Imagine having to read an entire cookbook, cover to cover, every time you wanted to cook dinner — just to find tonight's recipe.
With ten Skills files, each hundreds of lines long, that's thousands of tokens consumed immediately, before Claude had even begun thinking about your actual task.
Now, Claude first reads only the front matter of each Skills file — the small header block. That's a few lines per file instead of hundreds.
It uses those labels to figure out which Skills are relevant to the current task. Then, and only then, does it load the full content of the relevant Skills.
The desk stays clear. Context is reserved for the things that actually matter: your code, your conversation, the specific instructions for this specific task.
Here's the same idea in a step-by-step comparison:
Claude loads: every Skills file in full — the commit skill, the PR review skill, the documentation skill, the testing skill, all of them. The desk fills up immediately with information Claude doesn't need right now.
Claude reads: only the front matter of each Skills file. It sees name: commit and triggers: ["commit", "git commit"] and knows: that's the one. It loads the full commit skill only, leaving the rest on the shelf.
It's like the difference between a library with no catalogue system versus one with an index. In the old library, you'd wander every aisle pulling books off shelves to read their first pages just to figure out what they're about. In the new library, you check the card catalogue — a few words per book — find the one you need, and walk straight to it. The books didn't change. But the system for finding them became dramatically more efficient.
The instructions inside the Skills files didn't change at all. The full playbook is still there, still gets loaded when it's needed. Front matter just means Claude reads a small summary first before deciding whether to load the full thing. It's a smarter loading strategy — not a change to the skills themselves.
This might feel like an internal plumbing change — something that matters to engineers but not to users. It's not. Here's what the front matter update means for your actual day-to-day work with Claude Code.
Every token saved on irrelevant Skills files is a token Claude can spend on your actual code, your conversation history, and the task at hand. A less cluttered context window means Claude can hold more of your project in view at once — and reason about it more carefully.
Previously, every Skills file you added was a file that got fully loaded every session — whether it was relevant or not. With front matter, having twenty Skills files costs almost nothing extra, because only the front matter gets read upfront. The desk doesn't get any fuller just because the bookshelf has more books on it.
When Claude's context isn't cluttered with instructions for tasks you're not doing right now, it has a cleaner, more focused view of what you're actually asking. This tends to produce more on-point responses — less noise, more signal.
Because context is being used more efficiently, your conversations with Claude can go on longer before the "desk gets full" and older parts of your session start to fade from view. You don't have to restart as often.
Understanding front matter as a concept — "scan the summary before loading the full thing" — applies far beyond Claude Code. You'll see the same idea in documentation systems, email filters, content management systems, and database indexing. This is a recurring pattern in efficient software design. Now you know the grammar.
This change is a good example of something that's easy to miss but important to understand: in AI tools, attention is the scarce resource. Every word Claude has to read takes up space. Every piece of information loaded into context is space that could have been used for something else. The engineers who added front matter to Skills files were, essentially, helping Claude pay attention to the right things — and ignore the rest until it's actually needed.
Come back to this table whenever you need a quick reminder of what these terms mean.
| Term | Plain English | Analogy |
|---|---|---|
| Context window | The total amount of information Claude can hold in view at once during a conversation | A desk — you can only spread out so many papers before old ones fall off the back edge |
| Tokens | The unit used to measure how much space text takes up in the context window; roughly word-fragments | Square inches of desk space |
| Skills files | Documents that give Claude standing instructions for specific, repeatable tasks | A binder of laminated instruction cards — one per job type |
| Front matter | A short metadata block at the top of a file (before the main content) that describes what the file contains | The label on the spine of a binder, or the index card at the front of a recipe box |
| YAML | A simple format for writing key-value pairs, used for front matter and many other config files | A labeled form — "Field: Value" on each line |
| Lazy loading | The pattern of reading only a summary first, then loading the full content only if needed | Reading the menu before deciding what to order — not reading the full recipe for every dish first |
Claude Code now reads a short label at the top of each Skills file first, then loads only the relevant ones in full — keeping the context window clear and Claude's attention focused on what actually matters for your task.
Natural T3 continuations of this topic — not live yet, but they're coming.
Roles, constraints, chain-of-thought, few-shot examples — the repeatable system behind prompts that actually work.
How Claude and other AI tools connect to external systems, databases, and APIs. The protocol that makes AI agents actually useful.
How AI tools ground their answers in real data: embeddings, vector search, and why this matters more than fine-tuning for most use cases.