Transcript#

This transcript was generated automatically and may contain errors.

now introduce my colleague at Posit, Isabella, who does a lot of amazing work with AI, open source and engineering. And I'm very excited for her to speak today about Skills 101.

So for those of you who are interested in skills, this will be a great talk and it will bridge nicely into the next session that we'll have immediately afterwards with Ning and the team. So Isabella, over to you.

Thank you, Phil. Hi everyone.

I believe I should be sharing my screen. Thank you so, so much for joining. As Phil mentioned, you'll notice a lot of talks today either feature or mention this concept of a skill. And so if this is something that's new to you or you've heard of it, but have never tried it, this is meant to be kind of a foundational understanding of what skills are, why you would use them, and hopefully you can carry that knowledge over to the future sessions.

As Phil mentioned, hi, I'm Isabella Velasquez. I work on the developer relations team at Posit. I've been part of the R community for many, many years. I'm really active on social media. So if you ever have any questions, please do feel free to reach out.

And if you ever need the slides for references, the link is provided at the bottom here on the footer, pos.it slash skills 101. So please do reach out.

Why skills exist

So if you have ever used a coding assistant like Cloud Code or Posit Assistant, you'll know that these agents are incredibly capable, but often they don't have the context that they need to do the work that you need reliably. So for example, if you are asking it to follow a workflow, if you're asking it to create slides and you find yourself repeatedly being like, hey, please use these specific packages, or hey, use these brand guidelines every single time you give it a prompt, that is when you may want to consider using skills.

That's the kind of friction that skills were built to solve. So instead of opening a new project and copying, pasting the same block of organizational rules that you have, which works, but can be tedious and error prone, very easy to forget, you can solve this by packaging all of your procedural knowledge and things like your company, your team, your user specific context into portable version controlled folders and files that then your coding assistant can load on demand.

And my colleague, Gary Caden Bowie, who's a developer here at Posit, has said, if you find yourself saying the same thing to a model, it's a great moment to stop and make a skill.

if you find yourself saying the same thing to a model, it's a great moment to stop and make a skill.

What skills are

In terms of what skills are, at their core skills are Markdown files, and Markdown is a lightweight markup language with plain text formatting. If you've ever used R Markdown or Quarto, you have used Markdown. And these files live in a folder that your coding assistant can find. And many, many coding assistants follow the specifications for skills. And so they know where to look and what to do when they find these files.

And even though I mentioned coding assistants specifically, skills are actually supported in other sorts of programs. If you use Cloud Cowork, which is a desktop app, those actually support skills as well. But just in the context of today and this conference and us as you are users, I'm going to be focusing specific on coding assistants like Posit Assistant and Cloud Code.

And so in terms of these files and folders, they can live globally. And so this means that every time that you go to work with your coding assistant, it'll be there installed and ready to go. And skills can also be installed at a project level. So if you need a specific skill for a specific project, you could do that as well. And it won't be available to every single project that you open up.

Anatomy of a skill

And so here's an example of what that looks like. So if you imagine the left-hand side is my file explorer, I have a project open where I have a .cloud folder, within that, a skills folder, within that, a shinybslib folder, and then within that, a skill.nd, that markdown file that defines a skill. And because it's a markdown file, like a readme file, you can click that and open it up and take a look at what is inside.

And in terms of the anatomy of a skill, what actually defines a skill in this markdown file? So if you have used Quarto or R Markdown before, you may be familiar with this YAML header. So it's denoted by three dashes. And then inside those three dashes, there is a key value pair. So the key in this case would be name. The value is shinybslib.

And so the first required piece of a skill is this name, which must also match the folder name in which it is contained. That's how the assistant knows to actually go ahead and find it.

And then second is the description, which is probably the most important field. I think this can be a little bit misleading because it sounds like, oh, a description. I just need to write out what exactly this, what description of the skill. But in fact, this skill is how the model decides whether or not to load the full skill. It'll read this, it'll search for keywords and context, and then decide yes or no in terms of, yes, I'm going to use this skill. And so even though it sounds like it's a description for humans, it's in fact a description for the model. And so it's very important to know, or to write a very good description so that your skill is loaded appropriately.

And then below the YAML header is your actual content. So these are the instructions and the worked examples, the guardrails, whatever you want your model to do whenever you give it a command.

How progressive disclosure works

And in terms of how it works, the coding assistant would load skills through something that's called progressive disclosure. It doesn't load every single skill up front. Instead, it keeps a lightweight index of just those names and descriptions. And at startup, that's all that it reads.

Then you give the coding agent a command, like, hey, build me a BSLib dash. Hey, build me a BSLib dashboard. At this point, this is when the agent would, or the coding assistant would scan all those descriptions and then again, look for those keywords and be like, hey, does this match the command that I was just given or not? And again, this is meant to be just enough to know whether or not the skill is relevant. And only then, if it assesses, yes, this skill is relevant, will the coding assistant read in the full skill MD file. And then at this point, the coding assistant follows the different instructions based on whatever is specified in the actual body of the skill.

Skills vs. agent.md

And you may have heard of something called agent.md or claw.md. And so agent is more general, claw.md is specific for clawed code. And there are a lot of similarities. Clawed or agent.md are also markdown files with instructions for your model and your coding assistant in terms of telling it what to do.

However, one issue of putting everything within claw.md is this idea of context limits. So your model can only hold so much information at a particular time. And if your agent.md file is really, really big, it's going to hit its context limit really fast. And the issue with that is as you add on more and more instructions, your model doesn't actually necessarily get better. They can get worse. They can start to drift. They forget the rules that you gave it. It starts to hallucinate and so on. And then of course, as a user, what this means is every time you are opening up a project, your agent.md file is read, you're using more tokens than you absolutely need, which can incur further costs from you.

Versus a catalog of skills, which are again focused and it avoids this issue by having sort of a playlist only for the task at hand. They're small and composable, and you can just pick them out as you need them. So you and the model are really only paying for what you're actually going to be using.

Invoking skills

In terms of say you have your collection of skills, how do you actually invoke or use your skills? There's two different ways. One way is explicitly. So you can use what's called a slash command. So a forward slash and then the name of the skill to call the skill by name. And you could do this if you say no, that you're going to be creating a BS Lib app, but more likely you will be doing it automatically. So when you say, hey, build me a dashboard for so-and-so thing, it's going to read those names and descriptions. Again, based on it's like a small index, it's going to determine based on the context, whether or not the skill is relevant. And I'll let you know, hey, the skill is loaded. You know, in this case, Shiny BS Lib has been loaded. And so again, it only works as well as your description, which is another reason to spend a little bit of time on that field.

Live demo

So I wanted to show a really quick example of what this actually looks like. I do ask for your grace at being a life coding and then also LLNs. You never know what it's going to do, but here I have a folder and here are my files in the folder. I guess I should share. Oh, no, I'm just sharing. Here are the files in the folder. So I have, you know, a CSV file, three of them actually. And then I have Cloud Code open in my terminal. Another slash command that is helpful is clear, which clears the context window. And say, I'm going to ask Cloud, make me a Shiny app based on the data sets provided.

And so if you notice, I have to authenticate. There we go. And so if you notice here, it doesn't have a skill within this project and I don't have actually a BS Lib skill within my global directory. And so let's see what it does.

Okay, there we go. So if you notice here, it has prototyped a Shiny app for me. And if you notice really quickly at the packages that it loaded, it loaded Shiny, which is great and DT. But taking a quick look, this looks like a traditional Shiny app with the title panel and the fluid page and the sidebar layout, which is great. But let's say that I want to adhere to using BS Lib, which is a modern framework for creating Shiny apps instead.

So I'm going to open a new folder. First, let me exit here. And then this one actually does have a skill. So within these folders or within the folder, I'm sorry, there's also a .cloud folder. If I open this up, there's a skills folder. If I open this up, there is also a Shiny BS Lib folder and within that, a skills.md file. And if I open this up, this refers to what I just mentioned before with a name, the description that has all the keywords and so on, and then a ton of instructions that then the model would use to actually build the app that I asked for.

And so opening up Cloud again, and if I say build me a Shiny app using the data sets provided, I'm going to take its time. And it goes really, really fast, but one of the files that it reads is the skill. And then it actually even says, hey, I'll build a modern Shiny app using BS Lib specifically because that skill is available within the project. Oh, and there it says successfully loaded skill, which is great.

But if not, I hope this showcased how, in fact, having a skill in the proper directory within your project is immediately accessed by your coding assistant and then it uses it to actually create the dashboard. I'll come back to it and see once it's done, but just to keep going on our presentation.

Installing and creating skills

In terms of installing a new skill that isn't already on your computer or in your project, but it exists, there are a few different ways. So there is a command from Versa Labs called NPX skills, which you can run in the terminal. And it's really nice because it gives you an interactive picker for all of these different community skills. There are also a lot of different advantages for installing it this way because this directory also adds some metadata so that you can keep track of your skill and see where did you download this and so on. And then it also has things like security features because you are installing instructions from another source.

You can also just pass your coding assistant a URL and say, hey, make a skill from this. So like if a skill already exists and you give it a URL, I'll put it in the correct folder and so on. In addition, if you just have the file, say as a downloadable file, you can just plop it into your coding assistant and have it create the skill for you. Or because again, everything is living either in your global directory or your project directory, if you have that file, you can drag it and drop it into that folder yourself. And if you're working in R, there's a package called BTW, which has helper functions for installing skills from GitHub or R packages.

And if you want to create a brand new skill, you don't have to write a skill from scratch. In fact, you probably shouldn't. There are skills whose entire jobs are to write skills. And so in Posit Assistant, you would write the slash create skill or cloud code slash skill creator or from BTW, BTW task create skill. And then from here, you would describe what the skill would do and the assistant will scaffold the skill.md file for you.

AgentSkills.io is like the definitive guide for the skill specification. And they actually have a lot of great best practices. So in terms of how to create a new skill, they recommend including domain specific knowledge, being really specific in terms of your patterns, your edge cases, your conventions, and then working through a real task and then extracting it into a reusable skill rather than trying to work with kind of like vague definitions and build a skill from there. So definitely check out their website if you have a chance.

Managing and organizing skills

And this is a topic that I would love to hear from everybody in terms of if you are using skills, how do you manage or organize them? Because as you imagine, as your collection of skills start to grow, organization seems would matter more for you to remember like what exactly do I have and how does everything kind of relate to each other? And two examples of managing skills that I have found is asking your coding assistant to help you create a generic meta skill whose entire job is just wrangling your other skills. And then another one is grouping skills into subfolders within your skills directory. So that way, only the skills related to Pharma get pulled in, only to Shiny get pulled in and you can see them all in a single place.

When not to use skills

There are times that skills are not the right tools for the job. So if you have a lot of live changing data, you might wanna consider a model context protocol. There are lots of talks today too that mention MCPs. So definitely check them out to see how they contrast with skills. If you have a pile of documents, you wanna do retrieval augmented generation or RAG instead. But if what you're focused on is repeatable, know-how procedure, that's when you want to use skills.

And I mentioned earlier, skills are markdown files. That's a bit of a simplification. They can actually contain a lot of other things like scripts and references. I'm almost done, Bill.

Here are a few places where to find skills. And as Bill mentioned, the very next talk is going to talk about a collection of skills that you could start using and picking up for your Pharma work. And then here are a few other talks that specifically mention skills. At this very conference today that you should definitely go check out.

And finally, here is the app that Cloud Code created. And as you can see here, BS Lib is right at the top. And with that, thank you.

Q&A

Awesome. Isabella, we've got a couple of quick questions. I think there's three or four in the chat. I'm gonna leave those to you. I've got one quick one though. I thought we could just answer here. What's the difference would you say between a skill and a tool call or an MCP for someone new to skills?

Yeah, yeah. So I'm sorry that I had to go over it so fast, but skills is more on what to do, like these kinds of procedures and things like that. But if you have, if you need to require access to real life data, that's constantly changing, right? That's when you want to consider an MCP instead. And so both tools for Gen AI, but they have slightly different focuses.