As an AI practitioner, I’ve been using Claude Code for quite some time and have seen many tutorials explaining how to create Agent Skills within the Claude ecosystem. However, when I tried to implement the same concept forour enterprise solutionwithout relying on Claude, I quickly ran into a different set of design questions. What exactly defines an “agent skill”? How should it be structured? And how should skills be triggered and orchestrated in a custom agent framework?
In Claude, a typical Agent Skill is defined as a Markdown file containing a name, description, instructions, and scripts. This natural-language interface works well in many situations, especially when ambiguity is acceptable. But in production systems, precision often matters more than flexibility. One recurring challenge I encountered was skill triggering: sometimes a skill would be powerful and well-designed, yet Claude would fail to invoke it because the description was too vague.
For our agents, I need stricter guarantees—skills that trigger deterministically and behave consistently every time. That requirement led me to implement skills directly in Python with explicit logic. But doing so raised an interesting architectural question: if a skill is implemented purely in code, how is it different from a tool, a feature, or just another function? Even if these skills are reusable and invoked on demand, what actually makes them _agent skills_?
This article explores these questions and shares a practical perspective on designing and implementing agent skills for custom AI agents without relying on Claude.
Agent skills vs Tools vs Features ---------------------------------
Image by Author A toolis a primitive capability, or a single action the agent can take. Each tool does one specific thing. Tools are individual instruments, like hammers, saws, and drills.
* Example: Claude’s tools include things likebash_tool(run a command),web_search(search the internet),view(read a file),str_replace(edit a file),web_fetch(get a webpage),places_search,weather_fetchand so on.
A skillis a set of instructions for how to orchestrate multiple tools to accomplish a complex task well.A skill doesn’t give me new capabilities.It gives agents expertise incombining existing tools effectively.Skills are like a detailed recipe that tells the agents which instruments to use, in what order, and what mistakes to avoid.
* Example: The docx skill, for example, tells Claude to usebash_toolto runnpm install docx, then write JavaScript using specific patterns, then runbash_toolagain to validate the output, then usepresent_filesto share it.
A featureis a product-level concept, or something the user sees and can toggle on or off. A feature is enabled by giving the agent access to certain tools and skills.
* Examples: “Code Execution and File Creation,” “Web Search,” and “Artifacts” are features. So “file creation” as a feature is powered by the bash tool, the file creation tool, various document skills, and the present_files tool, all working together.
Skills are what bridge the gap between raw tool access and high-quality output. Without the docx skill, Claude could still technically create a Word document, but it might miss things like “always set page size explicitly because docx-js defaults to A4” or “never use unicode bullets.”
Do agent skills have to be in the format of markdown files? -----------------------------------------------------------
Not necessarily. The concept of agent skills is broader than the format.
A skill is fundamentallycodified expertise for how to accomplish a task well. That expertise could live in many forms:
* A markdown file with instructions (typical Claude Agent Skill) * A Python script that does the work directly * A config file or JSON schema * A set of example inputs and outputs * A combination of all of the above
In my case, thePython scriptseems appropriate because I need deterministic and reliable execution every single time with no variation. It’s faster, cheaper, and more predictable for a procedural process. Themarkdown instructionapproach becomes valuable when the task involves ambiguity or judgment. Sometimes, we need LLM reading instructions and reasoning about what to do next to add value over a rigid script.
Ahybridapproach is also common. I can keep my Python code and downgrade it to a tool implementation, but add a markdown skill file that helps the agents understand when to invoke my agent skill and how to interpret the results. A typical product iteration might begin with a Python implementation and gradually incorporate Markdown instructions, eventually forming a hybrid skill design.
Agent skill vs MCP? Agent Skill + MCP! --------------------------------------
Our agents already connect to data sources through MCP servers, but many of our agent skills also include the ability to read directly from databases. This raises a practical architectural question: when should an agent use MCP, and when should the capability live inside a skill? Anthropicexplains the distinction clearly with a helpful kitchen analogy:
> _MCP connects Claude to data; Skills teaches Claude what to do with that data._
* MCP provides the professional kitchen – access to tools, ingredients, and equipment. * Skills provide the recipes – instructions that tell the agent how to use those resources to produce something valuable.
In my design, I treat MCP connections as infrastructure and skills as orchestration on how the data is used.
MCP servers are responsible for exposing external data sources and services. For example, they may provide structured access to databases, logs, APIs, or internal systems. Their role is to make these resources available to the agent in a standardized way.
Agent skills, on the other hand, define how the agent should use the data from MCP servers and other databases to accomplish a task.
For this reason, I typically implement:
* Database access, APIs, and data retrieval as tools (or MCP capabilities) * Decision logic and workflows as agent skills
Skills as “Agentic RAG”
Ideally, the agent skills load information dynamically from tools when they are executed. This makes the pattern very similar to agentic retrieval-augmented generation (RAG).
Instead of preloading all context into the prompt, the skill can:
- Identify what information it needs
- Retrieve the relevant data through a tool or MCP server
- Process that data according to its instructions
- Produce the final output
Conclusion ----------
Anthropic introduced an important paradigm shift, and Claude’s implementation of Agent Skills offers valuable inspiration for building our own agent systems. As long as our skills capture the core purpose of what a skill is meant to do, which is encapsulating reusable on-demand capabilities for an agent, the specific format and implementation details can vary. Ultimately, the design decisions around when and how to use skills should be guided by the needs and constraints of the product we are building. *
Thank you for reading! I hope this has been helpful to you.