Agent skill - a complete guide with hands-on

Key Takeaways

and topic recently announced agent skills and it's getting widely adopted fairly quickly. So let's look into what this agent skills is. Agent skills give agents new capabilities and expertise and they are just folders with instructions, scripts and resources that the agents can discover and use to do things more accurately and efficiently. So why do we need agent skills? Basically, if you are authors or if you're developers, then basically we can build capabilities once and deploy them across several agent products. For example, we could just build a skill once and then we can give it to, you know, agent one or agent 2 and the multiple agents can use the same skill. This skills is quite different to that of MCP because MCP is what allows us to pull data from some external source. But with skill we can make use of this data that we pull that the agent pulls from an external system and it makes use of the skill in order to do further actions. So how do we use skills? Entropic already provides some pre-built agent skills that are common for task like you know when you want to deal with powerpoints or if you want to deal with excels or word or PDF documents there are some pre-built agents available. For example, if we go under the skills repository, we can see that these are all the different skills available. We have skills for canvas design. We have skills for, you know, MCP builder, PDF, parsing, and PPT. All sorts of common tasks that we normally deal with the that the agent cannot do on its own. But the good news is that we can also create custom skills. For example, if you look at this, to create a new skill, all that we need is a folder which has the name of the skill and under that we need to just have a skill.m MD file. And there are also additional folders we can create inside the skill. Say for example, any scripts that the agent needs to run or any references which are documentation about the code or if you have some templates or some of the resources, you can put it under assets. And if you structure like this and have a skill.md file then the agent will be able to make use of the skills. So one of the key idea behind skills why it became so famous is the idea of progressive disclosure to manage the context effectively. So whenever an agent is dealing with some information it puts in all the data into the context and the context just blows up. But that is really not the case when it comes to skills. It happens quite cleverly using progressive disclosure. So in the first step which is called the discovery step, the agent just loads only the name and description of each available skill. For example, if you just take a skill.md file, it needs to have two fields. One is the name and the next one is the description which gives a brief description about the skill. These are mandatory fields and once we have these fields in the skill.md it becomes a valid skill and whenever the agent wants to check what skills are available it just pulls this data and it ignores whatever is there underneath that. So that's the discovery stage and in the activation stage when the task match a skill description for example let's take the case of PDF processing and if the user is just prompting asking you know I want to be dealing with some PDF processing and provides a PDF then the agent decides that this skill is the one that I need to activate and we enter the activation phase and the agent starts reading the rest of the skill.md to understand what it can do with the skill. So whenever there's a match with a skill the agent reach the full skill.mmd and the instruction into the context because this is more of progressive thing or incremental thing it's called progressive disclosure and this is what exactly made skills super famous and the last step is of course the execution where the agent follows instructions that are available in the skill.md and it executes the steps in order to achieve what it wants. So let's quickly jump into VS Code and see what we can do in order to build a quick skill and make use of it in an agent. To begin with, we need to make sure that skills is enabled in our VS code. So I've just created a folder called clot skills demo and I've just opened it in VS code and I'm going to go to settings and settings under settings again and if I just search for skills we getting this and under chat use agent skills this checkbox is checked for me so if you want to disable you can uncheck it so I want to enable it because I'm now going to use the agent skills and these are the different locations where we can actually create new skills and put them for example we can have in the current directory I can create a GitHub hidden directory/skills and I can have new subsklls around that if I want something at the system level I can have you know in the home directory I can have a c-ilot directory and skills and under that I can have several skills what I'm going to do is I'm going to use this dot agents/skills so under here I'm just going to say agents/skills and inside that I'm going to create a new skill which is PDF PDF helper and inside that I'm going to create a new file called skill.md and I've straight away created a new skill called PDF helper and inside that I need to have a name and description. So for the name I'm going to say again PDF helper and for the description I'm going to say a simple skill useful for passing and creating PDF files. And if we just have these two fields then the skill is already created. I can go ahead and just give some instructions, some more instructions to be followed. For example, I'm just going to say PDF helper and I'm going to say respond to the user. Hey, how can I help you with your PDF today? So, this is the skill that we have created. Let's see if we can put this to use. Just going to close that and I'm going to open the chat window. And in the chat window, we need to go to this settings and we need to make sure that the reading of files in the workspace is enabled because the agent needs to now read this skill.md to understand that that skill is available at its disposal. And I've got other things enabled as well, but this is an important step. So once we have that enabled, we can choose any model that we want. I've chosen Claude Haiku 4.5. And I'm going to just ask list all the skills available. And let's see if it lists this new PDF helper skill. There you go. Straight away based on the available skills, here are the ones available to you. And it says PDF helper. A simple skill useful for passing and creating PDF files. Let's just try to invoke that if it can respond to us. Help me with PDF files. So it's reading the skill PDF helper and it says, "Hey, how can I help you with your PDF today?" So that's exactly what we said in the skill which is this one. So it's already responding with the response that it what we wanted it to use. So we can see where we can get with this. You can give very long instructions as to how we can go about it and we can add more scripts here if it's bit more complicated. So these are all several skills that we've got here. Let me just go into let's say canvas design and we could see that we've got this skill.md and there are some canvas fonts. So if you go into it these are all the different fonts that are available to be used inside it. And if you go into skill.md itself we could see that there's a name and the description which is a mandatory but we can also give other fields like you know license and we can just give our own terms. So these are the different optional fields as well. Despite having name and description which are mandatory, we can have license, we can have some metadata with the author, version and all these fields. And it's important to note that everything needs to be lowerase when it comes to the name. For example, uppercase PDF is not allowed because uppercase is not allowed and we cannot start with a hyphen as well. So or any special characters. So this is not allowed and consecutive hyphens are also not allowed. So two hyphens are not allowed. So it's best to stick with lower case with a single hyphen which is what I have done. I've just said PDF helper with one hyphen in the middle. So the skill that we define here has the ability to invoke tools that are available at our disposal and we can control what sort of tools or that the skill can use and we can restrict the skill from using tools that are like you know quite risky. That's why this field is here which is the allowed tools. So here we could just specify the list of tools that we can use. So this is the allow tools which is optional but we we can just give space delimited list of tools that are actually allowed. So once we give this field the rest of the tools are not allowed whatever the tools that you have. Now let's look into what exactly goes into the body of this uh markdown. So for the body we have quite a lot of flexibility. We just have to give the skill instructions and there's no formatting restriction. You could just write bunch of text and the agent is smart enough to understand what you have mentioned. But the recommended approach is to give step-by-step instructions and we can give examples of input and output and we can also say common edge cases. This is pretty much like how we would actually prompt a model. But the one thing is to note is that the agent will load the entire file once it's decided to activate the skill. So it's better to keep the skill.md as small as possible. If you think it's going to be pretty large one, then it's better to have additional directories. For example, whatever the scripts that needs to be used by the skill needs to go in a separate directory called scripts. And we can have separate references directory which contains documentation that the agent can read when needed. And we can also have some assets for example some templates. So we can have all the kinds of templates and images and data files, lookup tables and schemas everything in the assets directory. And the next important tip is to kind of validate the skill that we develop using the skills reference library which will validate the skill that you create. So all we have to do is skills ref validate and then just pass the skill that we create and it'll check and let you know that the skills.m MD is valid and follows all the naming conventions. That is all that we need to know about the specifications. What I've got here is a single page PDF file which has got some tableau data. It's just some prices about some tickets. I'm going to try and use the skill that we are creating here to extract data from that. Particularly it's a table of data. So hopefully we should be able to do it. Let's extract the data and see how far we can get. In order to do that what I've done is I've given this overview. This guide covers essential PDF processing operations using Python libraries and command line tools. It's particularly useful for extracting metadata, text, and tables from a given PDF file. And I'm just saying Python libraries, which is PIP PDF for basic operation. And to extract metadata, we are going to be using PDF reader. And we're also going to be using PDF plumber in order to extract any text data from a given PDF. And in order to extract some tables, we are again going to be using PDF plumber in order to loop through the different pages in a given PDF document and extract the table row by row. That's what we're doing here. We're just looping through the table and extracting row by row. And we also got some function using PDF plumber for advanced table extraction. You know, if a column has got multiple columns inside it and all those stuff, we'll be using advanced table extractions. And I'm going to create a new virtual environment called plot skills with py python 3.12. Give that virtual environment for the skill to be executed. I'm just going to say yes. And let's have that activated in case we want to do something inside it. And let's make sure this PDF plumber and everything is executed. What I'm now going to do is I'm going to open a chat session. I'm going to ask it to pass this pricing table. PDF using the virtual environment and I'm going to ask it to use the virtual environment cloud skills that we have created in order to install any Python libraries that are needed along the way. So I'm just going to say extract the Tableau data in pricing.pdf use the Python virtual environment. I'm going to be more specific here and I'm going to say use the cond virtual environment plot skills for installing any Python libraries and I'm going to hit enter. So let me start by reading the PDF helper skill documentation and then locate the PDF file. It says and it's activating using cond activate and it's trying to install a guess. So right so it's trying to activate the cloud skills and it's trying to install PDF plumber and panda. So I'm just going to allow it. So what it has done now is it's created this extract PDF tables.py and it's asking permission to run it. I'm just going to say allow. So it ran for a couple of minutes but it has eventually come up with this pricing table extracted CSV file and it says that extraction handled the PDF text encoding challenges and successfully passed all pricing data into a structured organized format ready for analysis or input into other systems. And it has also come up with a little bit of analytics as to key prices and it just says premium tickets range from this this this category 1 category 4 and all that and the extracted data as well. It's come up with some summary. On top of that it has also written all this Python files. It has written so much of code in order to extract the data from PDF. Let's have a look at the CSV file itself. So we've got this different dates on the left and we've got different prices. premium category 1, category 2, 3, 4 and it's got all the details perfectly fine. So it all looks good to me. It has done the job but it has turned out also so much of code. So that is exactly what I wanted to show to you. We saw an overview of the agent skills. We saw why we need it. Basically we need it because we can build a capability and reuse it again and again with multiple agents. We saw what the skills are and we saw how we can structure it by creating you know directories like this and creating a skill.md file and we also saw the significance of progressive disclosure. The context window is pretty small but by leveraging the progressive disclosure and we also saw what goes into the skill.md file which is the name and the description and we also saw other things that can go into the skill.md file. On top of that, we also have different specifications as to additional fields that can go like license, metadata, author name and all that. And we can also define what tools are allowed and what tools are not allowed. And eventually we did some hands-on. We created a PDF helper skill. And we wrote this skill.md file which is a tiny file with a little bit of instructions on how it can go about um dealing with the PDF file and extraction of table data. And we just gave a prompt asking it to you know extract tableau data in pricing tablet PDF. Use the cond virtual environment for installing any Python libraries. And this was the result that we got. We got the data extracted and we have the CSV file ready to be used in any other system. So thanks for your attention and I will see you in my next one. Take care.