Building with AI can feel like a cheat code, especially if you're new to coding or the coding language you're working with. However, your agentic coding session can go awry pretty quickly if it's given vague prompts and little to work with. You may think the solution is to just try a different model or agent, but what if the answer was simpler than that: be more directive to your agent with skills files. So, here's some tips and tricks you can use to set up your agents for success with skills files.
But first, let's define some terms. Skills files are a form of context engineering for your agent. Regardless of which model you use, you can add skills files as context. Then, when the agent runs, it will use the skills file as a reference when completing a task.
Skills files are generally markdown files, as their format is easily digestible by LLMs. Most agents allow you to add skills manually within your prompt, and some agents will automatically detect them if you're within a directory that includes a SKILL.md file.
Here are types of skills files which are good candidates to help agents work smarter:
- An internal library of best practices: Do you work in a particular way, or with a lesser-known language? Create an internal library to help guide the agent.
- Project structure scaffold: When starting new projects, how do you like your workstream to be structured? Create a skill file that lets the agent know naming conventions, version control, and more.
- Repetitive tasks automation: If you've done something more than once, you can automate it with a skill. This will help you to get the agent to complete that task more reliably with less effort from you on the initial prompt. If you've had a long agent conversation that involved some repetitive tasks you can actually ask the agent itself to suggest repetitive tasks to turn into skills.
- Modular tasks: Write skills in chunks. For example, create a skill that defines how to work with OAuth. Then, you can repurpose that skill in other projects that also need it.
Why do I need to build skill files?
Agents are only as good as the context they are given. Think of an agent like a new employee at a fast food restaurant. Yes, the employee could probably figure out how to work the ice cream machine on their own, but it would be faster if you showed them how to use it in the first place. That's what skill files do — they give agents the directions they need to succeed much more efficiently than if they're left to figure out the task on their own.
When building skills files, you're putting your institutional knowledge to work. Whether it's telling the agent about how your business model works, or giving it a standard operating procedure (SOP), you are the expert. With that, my recommendation is to not have AI write your skills files for you. While they can help with refining and formatting later on, the main point of a skill file is to tell the computer something it doesn't know.
Do MCP servers replace skill files?
You might think that if a system has an MCP server available, there's no reason to build skill files. However, skill files and MCP servers can actually work in tandem. For example, if you're working with the HubSpot Developer MCP server, creating skill files can make your agent work more efficiently. You can even reference specific MCP server tools in your skill file so the agent knows exactly which tool to invoke. MCP servers themselves can serve skills to your agent to enable the agent to understand how to use the tools better. Creating your own skills though lets you add your personalized preferences.
How do I write good skills?
If you've never written a skill before, it may feel a little overwhelming. There are many great resources available, including open source skills you can download from sites like skills.sh. These skills range from product-specific to persona-based, and you can download them to see how skill files are generally formatted. Always personally read skills you download — especially if you don't know the author — as skills could hide malicious instructions.
If you want to build a skill from scratch, start by writing down in natural language what you want the agent to achieve. That's the main gist of a skill! From there, you can refine it, whether that means breaking the skill down into sequenced instructions, or adding in diagrams like decision trees, the way you format the skill can help the agent use it more effectively.
Agents read files from top to bottom, so add the most pressing information at the beginning of the file. Separate sections by clear headings to help the agent stay on track and not get lost in a wall of text.
Remember that simpler is better. If you think your skill file is starting to cover too many topics, break each topic down into its own file or separate skill. Having smaller, more digestible markdown files is easier for the agent to use.
A really good skills setup for agents often have a lot of smaller, more modular skills than giant monolithic "do this, then this, then that" skills. This can enable the agent to do a more varied set of tasks with nearly the same information. You can even reference and hint to the agent about other skills it should use when it's in specific situations.
For example if you had a web accessibility skill that gives the agent a ton of best practices on Accessibility, and how to test it — that skill can basically be referenced in another skill like "Create a website module", and "Create a website template". This enables your skills to be lighter weight, and focused on their specific concerns. The key to a good modular skills set up is providing good descriptions and skill names to enable the agent to really know when to automatically use them.
If you add in relevant links to online documentation, preface it with a note about what the documentation is about and what the agent should look for. Giving an agent a URL without context consumes more tokens, because the agent has to read the entire webpage and then parse out what relevant information it needs from it.
Available components for UI Extensions
https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensions/ui-components/overview.mdThe LLM can intuit some things from the URL but giving it more clarity can help it know when to fetch that page.
It's like when you perform a normal web search. You don't just see a list of the URLs for the pages, but instead you see the title and a snippet or description of each page so that you can determine if that link is relevant to what you're looking for.
And, don't forget to add frontmatter — general information at the top of a markdown file for the agent — that includes the name and description. Here's an example of some frontmatter:
In the description, you can also add trigger words for the agent to listen for to invoke the specific skill. In the case of the above example, you could add to the description: Call this skill when the user asks to resolve or triage a ticket.
After you've written these skills, you can upload them as context to the agent you're using, or if you're using something like Claude Code, you can create a .claude folder at the top of your directory with a nested skills folder inside. Then, inside of the skills folder, you can directly add named markdown files there, such as app-card-scaffold.md. When you use Claude, whether through your computer's terminal or a chat interface, Claude will auto-detect the skills.
How can I make skills work for my job?
Some Best Practices for Every Agent User
Familiarize yourself with the domain of what you're trying to get the agent to do (domain meaning realm of knowledge in this case, not domain name). For example, if you're trying to get the agent to build software for you, but you've never read the platform's documentation at a high level, you literally do not have the words needed to properly explain what you want from the agent.
Give the agent knowledge on that domain of expertise. If documentation exists, give the agent links to the documentation. If you don't even know where to start — treat it like you are trying to learn that domain yourself. Ask an agent to deep research the topic, asking it specific questions about things you don't know the answer to. Take that deep research regardless of if you directly read all of it, and use that to help the agent understand the topic so that it can try to better interpret what it thinks you're asking it to do.
Consider when it makes sense to schedule an agent to do something, or set up triggers so that when something happens an agent does something. Consider using agents to make your agents work better, doing things like keeping the data your agents have access to up-to-date, free of bad data and more. An example would be if you have an AI note taker in your meetings, having an agent update your project management system accordingly for you, and then giving the agent you're using to get the actual tasks done access to read from that project management system. This enables the agent to automatically get the up-to-date context it needs to do its work properly.
Anticipate change. Your skills files should try to be written in such a way that you are not directly storing very much knowledge in the skill itself rather giving the agent the ability to get the most current knowledge for itself. The best example for this is developer centric but it applies to everyone: If you included in your skills files instructions that were specific to a certain version of a library, or certain version of a platform or system, suddenly when that version becomes outdated your skill file needs to be remade. You can avoid this by instead focusing on the high level ideas in your skills and linking off to sources of truth such as documentation so the agent can then find the most current information on its own. Even if the link becomes outdated, fixing the issue becomes just changing the URL and saving the skill file.
In your skills communicate the high level goals of the skill. This enables the agent to reason about what your actual objectives are during the session and if they match what the skill is for. If they don't match what the skill is for the agent can perhaps take information from your skill instead of doing verbatim what the skill says, in order to execute the task. Being goal oriented also can help when LLM models get better as the LLM may get better to the point where it doesn't need your step by step checklists, instead it understands the problem you're trying to solve and can reason about the order of operations situationally. This keeps your skills files useful over time.
Some Best Practices for Developers
If you're using these skills for coding, you can tell the agent to directly call CLI commands. This can help the agent make quicker decisions, because they don't have to search the web for the answer, but can instead run the commands in its own terminal. You can also have the agent run scripts that you've built for specific tasks. This can be helpful if you're using a less-common language, or doing something that is very specific to your company or industry and you need the response to have the same outcome each time someone runs the agent.
Do you regularly make calls to a certain API with your agent, or perform a task in a very linear way? Try asking the agent to create a script in your skill file for handling that task. There may be pieces that still require the LLM, but by splitting things like fetching data, and how the LLM handles that data, you can save tons of tokens and wasted code generation since the LLM can just re-use the script it already has.
Also, agents work best with common languages. Because they're trained on open source code, the more common a language is, the more the agent will understand it. So, skills come in particularly handy if you're working with a very specific language, or if you're using a language in a non-standard way. For example, app cards can only use the UI extension components that are pre-defined by HubSpot. Before skill files, an agent would build its own React components that weren't compatible, but after, it understood to only use the correct UI extension components, including compatible props. This made the app cards built by the agent much more stable.
If there are skills you want to share across your teammates and you use Claude, you can turn your skills into Claude plugins. Claude plugins are packaged skills you can download from either the Claude plugin marketplace or directly, and then call them using slash commands. Skill files themselves are contained to their local directory you're working in, while plugins can be used across multiple directories. So, if you're onboarding new members and you want their Claude Code to run the same way yours does, create plugins they can tap into. Additionally, the Claude plugin marketplace has a large number of plugins you can download and start using without building the skills yourself.
Conclusion
Skills are a great way to help your agents work smarter, not harder. You're building the instructions they need to work more efficiently and produce better, more reliable results. While it takes some upfront work to compose and refine skills, they'll boost productivity once you start using them, turning your agent into a better pair programmer, market researcher, or sales assistant.
