- Think of skills as modular, reusable pieces: combine them to get the outcome you want. A set of three skills that can all be used together is far more powerful than a single comprehensive skill that directly tells the agent what to do at every step. It enables the agent to use each skill individually and conditionally, mixing and matching for the situation. Inside your skills you can mention the other skills to encourage the agent to use them depending on the situation.
- Put effort into writing a good description: make it specific enough that the agent knows when to use the skill without you prompting it directly.
- Link to documentation rather than explaining how things work: if your skill is related to building something on HubSpot, include links to HubSpot developer documentation rather than directly telling the agent how things work. This keeps guidance up-to-date as LLM models improve. Focus your skills on how you want things built: your team’s practices, the way you like to work.
- Focus on the outcome you want: what does a good end result look like? Consider providing examples.
- Use AI to help you craft the skills: this is a useful time to use one of the deeper thinking models. If a skill is telling the agent to do something programmatic like call an API, tell the agent helping you craft the skill to create a reusable script for doing that, so every time the agent needs to make that call it doesn’t need to regenerate code.
- Consider how you want the agent to communicate with you: if you prefer that the agent display lists as a table with numbered rows so you can respond with instructions per item, include that in your skill.
- Tell the agent the “why” behind the instructions: this can sometimes be more important than the instructions themselves, especially with models that are better at deep thinking.
- Encourage the agent to ask clarifying questions related to what the skill is focused on so it can give better results.
- Watch the tool calls and reasoning every time you use the skills. Work with the agent to refine them to work more efficiently over time.
Best Practices
Agent skills
What skills are and how to write effective ones for your agent.
Some agentic tools support a feature called skills. Skills enable your agent to act more intelligently, and can be as simple as markdown files that act like prompts, or get more complex by incorporating scripts that the agent can execute. Skills let you move from writing lengthy, vague prompts to communicating naturally and getting consistent results with less instruction.
When creating skills, some best practices to follow:
Last modified on September 9, 2026