I just started using Agentic AI. I can say there are PROs and CONs on using your favorite AI Client to help you create and debug your applications. There are a lot of AI Clients out there; Claude Code, Codex, Kiro, and OpenAI to name a few.
Whatever client you use and whatever Model Modes you are using, I feel that you will get a better usage of your tokens with SKILLs.md. Well.. not always but depends on your use cases.
When SKILLS.md saves tokens
If your agent retrieves only the relevant SKILLS.md for the task, it can significantly reduce the number of tokens sent to the model.
For example, instead of including a single 10,000-token system prompt describing 50 tools:
- Tool A
- Tool B
- Tool C
...
- Tool Z
your agent can do:
User: "Terminate employee John Smith"
Retrieve:
skills/hr/SKILLS.md
Now the model only sees the 200–500 tokens relevant to employee termination instead of the entire tool catalog.
When SKILLS.md doesn't save tokens
If you simply append every SKILLS.md to every prompt, you won't save tokens. In fact, you'll likely use more because you've added another layer of documentation.
The efficiency comes from selective retrieval, not from the existence of the Markdown files themselves.
Other token-related benefits
Even when the token count is similar, SKILLS.md can reduce wasted tokens by helping the model:
Choose the correct tool on the first attempt.
Avoid unnecessary reasoning about irrelevant capabilities.
Make fewer failed tool calls.
Produce shorter, more focused reasoning.
That can reduce the overall tokens consumed across an entire task, especially for multi-step agent workflows.
Bottom Line
SKILLS.md is not inherently a token optimization technique. It's an organizational mechanism. The token savings come from pairing it with a retrieval strategy that loads only the documentation needed for the current task. As your agent grows from a handful of tools to dozens or hundreds, this approach becomes increasingly effective for both cost and model performance.
Top comments (1)
curious if you've noticed any specific prompts that work better for the skills.md format compared to a standard system prompt