This summary is produced by the author, and not by AI.
AI skills, at their very simplest, are just text prompts stored in a SKILL.md markdown file, along with some optional supporting reference, script, and asset files. There is no magic here: a skill is context you give the agent, packaged in an open standard. Even so, skills are quite valuable for making AI agents more reliable and for sharing capabilities with the rest of your organization.
Installing a skill just means placing its folder where your harness (such as Claude Code or GitHub Copilot) looks for skills: either in a configuration folder specific to a project or in a global configuration folder. At the start of a session, the harness reads only each installed skill's name and description, so the agent knows the skill exists and when to use it.
Once a skill has been installed, invoking it in Claude Code is simply a matter of typing a slash and then the skill name, along with any supporting guidance; other harnesses have their own equivalent methods. The harness then loads the skill's instructions into the agent's context, like a reusable prompt. Skills can also be loaded by the agent itself when the skill's description matches the task at hand, unless that is specifically disabled in the skill definition. In the screenshot below, you can see the list of skills that show up when typing /te-. Pressing enter loads the skill, and pressing tab completes the skill name.
Pointing your agent at a skill file and telling it to read the file is not the same as installing a skill. Doing so misses out on all of the integration with the harness, as well as the progressive disclosure benefits we cover below.
One of the benefits of skills is that they are designed to take advantage of progressive disclosure. This means that the agent reads progressively more about the skill, on-demand. This is valuable because always-loaded context increases costs and can degrade agent performance.
Another benefit of skills is that they are easy to share and collaborate on. While CLIs and MCP servers are useful, they make more sense as packaged programs shared from a central source and consumed by users. Skills, on the other hand, can be kept in a Git repository and versioned like any other piece of code or documentation.
Skills exist in a hybrid space between documentation and code. Skills may include executable code, but the prompt itself is not code. You should treat skill writing as a writing and communication challenge, but you should store, track, and maintain them as if they were code.
In fact, in a recent article by Anthropic, they recommended treating the skills for a data model as first-class citizens and storing them alongside the code for the model. This was to ensure that skills were updated frequently along with the model, otherwise the effectiveness of those skills would degrade.
Skills are a simple, open standard originally created by Anthropic, who also created and opened the Model Context Protocol (MCP) standard. Skills were presented as a complement to MCP servers as a way of extending AI agents. MCP servers are not as flexible as skills, since they provide a predefined set of tools that the user can’t modify.
As far as technical standards go, the one for agent skills is ridiculously simple. A skill is a markdown file consisting of three parts: the name of the skill, a short description of the skill, and then a prompt of general instructions for the AI. The name and the description make up the frontmatter, a small metadata block between two --- at the top of the file. The frontmatter is YAML so must follow that syntax, the rest of the file has no structural requirements at all. The frontmatter can also contain other optional metadata, like the tools the agent is allowed to use.
Optionally, it can include a references folder for reference material that should only be loaded when the situation calls for it. It can also include a scripts folder for code that the agent can run. Finally, you may include other folders, such as an assets folder.
So, if you could write out this standard on the back of a napkin, why does it need to be a standard at all? Well, we think there are two main benefits of this being a standard. First, it leads to more reliable integration with various coding harnesses. That said, implementation varies quite a bit by harness. The allowed-tools setting is currently experimental, for example.
Second, skills, unlike MCP servers, naturally encourage progressive disclosure, which reduces cost and protects output quality when using AI agents. The frontmatter of the skill is the part that’s always loaded into the context window of the agent. The full instructions are not read until a human or agent decides to invoke that skill. The frontmatter thus plays an important role in automatic skill usage of your agents. Using a vague name or description means the agent won't load the skill when it should, and works unaided when help is available. A description that overpromises makes the agent load the skill on tasks it wasn't written for, steering it down the wrong path.
If the frontmatter is the always-loaded first level, and the prompt is the read-when-invoked second level, the references folder adds a third on-demand level. The skill's prompt can point the agent at files in the references folder, which it only reads when the situation calls for them. The skill we provide for the TE CLI contains guidance on combining it with the Fabric CLI in a reference file, useful in the sessions where it comes up but dead weight in others. Each layer's job is to tell the agent when to read the next: the description says when to load the skill, and the skill's instructions say when to read each reference.
It's easy to lump skills in with MCP servers and other plugins, but they solve a different problem. Whereas an MCP server gives the agent tools (a predefined set of functions it can call and which you can't modify), a skill gives the agent context: what it should do, in what order, pitfalls to avoid, and how you prefer it to be done. When an agent fails at a task, it's usually not because it was missing a tool. It already has a terminal and can read files, so mechanically it could do the work. What it lacks is the knowledge it can't derive from its training data, which only you and your colleagues know.
That said, skills can expand what an agent is able to do. A skill can bundle scripts, binaries, and even full programs, with instructions telling the agent when to use them. Anthropic's document skills work this way: collections of Python scripts with instructions on how to use them.
The language models that agents run on keep getting better at the technical fundamentals on their own. Agents read --help output, inspect error messages, and already know technologies like DAX, SQL and Python from training. Skills explaining the technicals can be useful, but every model release makes them a little less needed. Technology that runs ahead of the training data, however, does make sense to encode in a skill.
But models will never pick up from training data how your business works. They know how to write SQL but they can't know which SQL to write. Skills that encode business processes and definitions keep their value better than the technical ones.
Writing your first skill is easier than it might seem. Take a task that you already do and have the agent attempt to perform it. Then note any areas where the agent made incorrect assumptions, got confused, or needed guidance. Put those notes in a SKILL.md file, add a name and a description of when to use it, and you have a skill. Then, importantly, test the agent again with the skill installed and iterate. As models get more powerful, less and less needs to be explicitly said.
A skill should contain guidance that is not in the model’s training data, preferences, or information specific to you or your organization, and pitfalls or gotchas that you have observed the agent running into. If the guidance only ever applies to one repository, it should be in that project's agent instructions instead. Only make it a skill when it is reusable across projects, or if the guidance should only load on demand. One way of thinking about this is if you hired someone who was technically brilliant. They excel at DAX on their first day, but they can't know that your organization sells kits that hide their component parts, or that finance resets standard costs every January. Nobody can know those things from the outside, so they must be encoded in a skill.
Below is a simple example of what that may look like. An agent without knowledge of how your bill of materials works is likely to rank parts by invoice lines, missing the parts that mostly sell inside kits but not much by themselves.
---
name: bill-of-materials
description: Service kits do not show component parts in sales data. Use when analyzing part-level sales, demand, margin, or stock levels.
---
We sell parts individually and as fixed-content service kits. A kit is its own SKU; the invoice line does not show the components. Kits contain parts, not other kits.
- Don’t rank parts by invoice lines alone. A part that’s mostly sold inside kits will look like it barely sells, even if those kits sell well.
- For part-level demand or profitability, first break kit sales down into their components. The kit contents can be queried from different sources: references/kit-sources.md.
- Kits are priced below the summed list prices of their components. When allocating kit revenue to parts, allocate by standard cost share, not list price.
- Part margin uses standard cost, not last purchase price. Finance resets standard costs every January so margins can then shift even when sales did not change.
- We hold stock of components, not assembled kits. For availability questions, check the components. The scarcest part determines kit availability.
- If a kit ever appears as a component in another kit, the data is wrong: kits should not contain kits. This is almost always due to a copy error in the ERP. Stop and relay the affected kits to the user so the rows can be fixed.
A skill should not contain information the agent can cheaply re-derive on its own, or information that the agent is heavily trained on (such as Python fundamentals).
Writing the skill is only half the job. A skill is context, and context can hurt as easily as it helps, so you need a way to tell whether the skill you just wrote earns its place. That is the subject of part 2 of this blog pair, along with why the skills you install from elsewhere are yours to own.
Skills are a flexible and powerful standard for guiding AI agents in certain tasks. They can be as simple as a dozen lines of text and are context, not tools. Knowledge that will never be in the training data, such as your business's processes, is most valuable to encode, while technical knowledge on how to use common tools becomes irrelevant the fastest. Skills should be written cautiously, iteratively, and concisely.
Take your semantic models further with Tabular Editor.
Give Tabular Editor a spin