Agent Skills Architecture Deep Dive: From Skill.md to the Core Logic of Tool Calling

What Are Agent Skills

In discussions around Agent development, Skills (agent skills) is a concept that has been frequently mentioned lately yet is often misunderstood. According to the official Agent Skills documentation, agent skills are "a lightweight, open format for extending AI Agent capabilities with specialized knowledge and workflows."

The core of this definition lies in the phrase "extending capabilities." Large language models themselves — whether DeepSeek^Ad, Kimi, Doubao, GPT, or Claude — are fundamentally just a "brain" with analytical and reasoning abilities. They don't come with any additional built-in functionality. When we want a model to complete specific tasks for us, it actually has no idea what tools, methods, or skills it has available to call upon. That's where Skills come in: they allow an Agent to iteratively build a reusable set of skills based on project requirements, enabling it to handle complete business workflows.

From a technical ecosystem perspective, Agent Skills differ from the "tool chains" found in mainstream Agent development frameworks like LangChain, AutoGen, and Coze. Tool chains are typically code-centric and rely on framework-specific API integrations. Skills, by contrast, adopt a more "declarative" design philosophy — using structured documents to describe capability boundaries, allowing skills to be reused and shared across different Agent platforms. This design is similar to npm packages or PyPI modules: developers can publish and reference others' Skills without building every capability from scratch. This is precisely why Skills are defined as an "open format" rather than a proprietary specification tied to any particular framework.

Skill.md: The Minimal Building Block of a Skill

At the heart of any Skill is a SKILL.md file, which carries the skill's metadata. Of all the metadata fields, the two most fundamental and non-negotiable are:

• name: The name of the skill
• description: A description of the skill

If you're creating a custom Skill or using a pre-built one from an online source, make sure it includes these two fields at minimum. Beyond that, a complete Skills directory structure typically includes additional optional components:

• scripts: External execution scripts, such as Python scripts or batch commands
• references: Additional reference resources, such as data files
• resources / assets: Templates, static pages, static stylesheets, and other assets

There's an important "minimum requirement" to keep in mind: a Skill only needs a single SKILL.md file to run — everything else is optional. That said, if you want to unlock the full potential of a skill, it's worth filling in as many of these components as possible. Whether you need them ultimately depends on the complexity of your use case. A simple weather query Skill, for instance, might just call an open-source API directly and have no need for scripts, references, or any extra structure.

The Underrated description: It's Not Written for Humans

One point worth highlighting on its own — something emphasized repeatedly: description is not written for humans; it's written for the large language model.

This is something developers easily overlook. In LLM development, we often define something called a tool, which is essentially a function or method. Once a tool is defined, it's common practice to attach a descriptor to it using a standardized format — this descriptor describes what the tool does, i.e., its description.

Many developers treat description like a project README. But the intended audience is completely different. A README tells people what the project does, how the architecture works, and how features are organized. A description, on the other hand, is how you tell the large language model what a given tool or skill can actually accomplish.

Only when the model understands the description can it correctly "discover" these Skills and trigger them when encountering a relevant scenario. In other words, the quality of your description directly determines whether the model can identify and use your skill at the right moment. This is why it bears repeating: anywhere a description appears, it matters — not just in Skills, but in tool definitions as well.

A Note for the Vibe Coding Era

Here's a related reminder worth keeping in mind: opportunities to write code by hand are becoming increasingly rare, with many developers relying on AI-assisted coding (vibe coding) to implement features. Even so, for critical components like description, it's still advisable for developers to personally review and ensure quality. These descriptions directly affect the accuracy of Agent behavior, and leaving them entirely to auto-generation tools often produces results that fall short.

To understand this from the perspective of how large language models work: when an Agent is processing a user request, the model must choose from a list of available tools or skills. This selection process isn't driven by hard-coded rules — it relies on the model's semantic understanding of description text to match user intent. This is technically referred to as "tool routing" or "function calling." In OpenAI's Function Calling, for example, the model semantically compares the user's input against each tool's name and description before deciding whether to call a tool, and which one. If a description is vague or unclear about what scenarios it covers, the model will either fail to trigger a call or trigger the wrong tool. In this sense, description is essentially a "calling contract" written for the model — it deserves the same careful attention you'd give to designing an API interface.

Vibe Coding is a development style that has grown popular in recent years, where developers primarily describe their requirements to AI and let the AI generate the code, rather than writing every line of logic by hand. This approach dramatically lowers the barrier to programming, but it also introduces a hidden risk: developers may not scrutinize the quality of AI-generated content closely enough. For configurations like description that directly influence model behavior, AI-generated wording tends to be generic and lacks scenario-specific precision, potentially causing the Agent to misfire in production. This isn't a rejection of AI-assisted coding — it's a reminder that the more "invisible" a configuration seems, the more it warrants human review, because these settings are often the starting point of the entire system's behavior chain.

Are Skills Really "Just a Markdown File"?

There's a claim circulating online: Skills are basically just a Markdown file.

From a minimal-construction standpoint, there's some truth to this — after all, SKILL.md is the only required file. But concluding that Skills are merely a Markdown document is an oversimplification.

A truly powerful Skill is typically a combination of SKILL.md (metadata and documentation) + scripts (executable logic) + references (referenced resources) + template assets. The MD file is just the entry point and the "manual" — what actually makes a skill functional in practice is the complete workflow and resource system behind it. Reducing Skills to "just a Markdown file" causes people to miss the real value: Skills as a framework for extending Agent capabilities.

How to Learn: Reading the Official Docs Is Still the Best Path

A straightforward but effective learning tip: when picking up any new technology or concept, the best source is always the official documentation.

The Agent Skills official site is entirely in English, but the writing is generally easy to follow. With a translation plugin (such as a select-to-translate extension), there's virtually no reading barrier. Beyond the basic definitions, the official site also offers Quick Start guides and Best Practices — first-hand materials for building a solid, systematic understanding. Don't use "it takes too much time" or "I can't read English" as excuses. In an era where AI assistance is always within reach, neither of those reasons holds up anymore.

Summary

Understanding Agent Skills comes down to grasping three levels. First, it is a lightweight, open format for extending Agent capabilities — filling in the gap that LLMs leave as "brains without hands." Second, SKILL.md is the minimum required unit, with name and description as the core metadata, while full capability depends on optional components like scripts, references, and templates. Third, description is the invocation basis written for the model, and its importance extends across the entire LLM development landscape. Advanced topics such as comparing Skills with Multi-Agent architectures and progressive disclosure are worth exploring further once these foundational concepts are firmly in place.