Agent Skills in Practice: A Complete Tutorial on Building an AI Skill System with OpenCode

What Are Agent Skills: Giving Models the Ability to Temporarily Learn New Capabilities

Agent Skills have been a hot topic in the industry recently, but many people don't have a precise understanding of what they are — some think they're an upgraded version of prompts, others see them as an integration of tool calls, and some treat them as a plugin system. None of these interpretations quite hit the mark.

In one sentence: Agent Skills are a mechanism that lets models temporarily learn new capabilities at the right moment. There are three key phrases worth unpacking here:

• At the right moment: Skills are only triggered when genuinely needed, avoiding wasted compute and excessive token consumption.
• Temporary capabilities: Called on demand, not permanently resident in memory.
• Breaking native limitations: For example, parsing PDFs or executing scripts — enabling models to do things they otherwise couldn't.

This is precisely what differentiates Agent Skills from existing solutions like MCP. To understand this distinction, we first need to see the limitations of a bare model.

The Inherent Shortcomings of Bare Models

A pure large language model, without access to external tools, simply cannot do many things. Here's a concrete example: in OpenCode, if you add a PDF file and ask the model to summarize its contents, it will flatly tell you "I can't do that."

This isn't because the model's parameters aren't intelligent enough — it's because models inherently only understand and generate text. They don't know what a PDF's structure looks like, nor can they parse one. The core architecture of a large language model is an autoregressive text generation system based on Transformers. Its training data consists of tokenized text sequences, and its inference process is next-token prediction. This means the model fundamentally only understands serialized textual information — it has no "eyes" to parse image pixels, no "hands" to manipulate the file system, and no built-in binary decoder to interpret PDF, a complex document format defined by Adobe. PDF files internally contain cross-reference tables, embedded fonts, graphics streams, and other structured binary data that lie entirely outside a language model's perceptual range. The model's capabilities are inherently limited — that's an inescapable reality.

The Essential Difference Between Skills and MCP: Progressive Disclosure

In the past, the industry primarily had three ways to break through these limitations: stuffing rules into prompts, using Function Calling to execute external code and return results, and using full-scale tool protocols like MCP. Agent Skills represent a fourth path.

Function Calling is a mechanism first popularized by OpenAI in mid-2023. It allows models to generate structured JSON output during conversations, declaring their intent to call a predefined external function along with its parameters. The system receives this declaration, executes the actual function logic outside the model, and returns the results for the model to continue reasoning. This mechanism is essentially a division of labor — "model makes decisions, external systems execute" — but it requires fully describing the schema definitions of all available functions in each request's system prompt, including function names, parameter types, parameter descriptions, and so on. This is one of the sources of context bloat.

MCP (Model Context Protocol) is an open standard protocol officially released by Anthropic in late 2024, designed to establish a unified connection method between AI models and external data sources and tools. Its design philosophy is similar to USB-C — providing a standardized "port" that allows any tool to connect to a model in a uniform way. MCP uses a client-server architecture, communicates via JSON-RPC 2.0, and supports three core primitives: tool invocation, resource access, and prompt templates.

Three Major Pain Points of Traditional Approaches

Whether it's prompts or MCP, the essence is telling the model upfront: "You can do A, B, C, here's how each one works, and here are the rules..." followed by a massive wall of instructions. The problem is: regardless of whether you use them or not, all these rules get stuffed into the context with every conversation.

This leads to three serious consequences:

1. Context grows increasingly long, driving up usage costs;
2. Token consumption continues to climb;
3. The model's attention gets scattered across numerous rules and explanations, unable to focus on the core task.

The third point deserves deeper understanding — the computational complexity of Transformer self-attention scales quadratically with sequence length (O(n²)). When large amounts of irrelevant tool descriptions occupy the context window, they not only increase computational overhead but also dilute the model's attention weight allocation toward truly critical information, degrading reasoning quality. MCP's "full exposure" characteristic means all registered tool descriptions must be injected into the context window with every interaction. When the number of tools grows to dozens or even hundreds, this context occupation balloons dramatically.

The Two-Layer Information Design of Skills

Agent Skills take the opposite approach. By default, they only tell the model the names and descriptions of available skills — the specifics of how to execute them are withheld. Each Skill exposes only two layers of information to the model:

• Name: What the skill is called;
• Description: When the model should use it.

The specific execution rules, invocation methods, and operational details are hidden from the model. Only when the model is executing a task and actually needs a particular skill does the full content of that Skill get loaded. This is what's known as on-demand loading (lazy loading).

This lazy loading philosophy has deep roots in software engineering. Lazy Loading is a classic engineering pattern widely used in database ORMs, frontend resource loading, operating system memory management, and more. For example, modern web pages use image lazy loading — images are only fetched via HTTP requests when the user scrolls them into the visible viewport, rather than loading all images at once when the page opens. At the operating system level, the virtual memory paging mechanism follows a similar philosophy: physical memory only loads the pages currently in use, while the rest resides on disk. Agent Skills migrate this concept to AI context management, implementing a "declarative registration, runtime loading" pattern that effectively alleviates the pressure on the scarce resource that is a large model's context window.

To put it in plain terms: you know in your head that you have a certain skill, but you don't need to memorize the specifics of how to perform it — you only pull out the manual when you actually need it. The MCP approach, by contrast, is like reading through every single manual before starting any task.

Agent Skills vs MCP: Engineering Thinking vs Protocol Thinking

The comparison between these two can be clearly laid out:

Dimension	Agent Skills	MCP
Loading Method	Only loads names and descriptions; details loaded on use	Full loading regardless of usage
Context Usage	Significantly reduced	Explodes as tools increase
Decision Model	Model autonomously judges whether and which to use	All tools laid out, selected by rules
Scalability	Skills can be added infinitely without slowing conversations	More tools = higher cost and latency
Positioning	More like an intelligent agent	More like a toolbox

One-line summary: Skills embody progressive disclosure as engineering thinking; MCP embodies one-time exposure as protocol thinking.

"Progressive Disclosure" is not an original concept from the AI field — it originated from Human-Computer Interaction (HCI) design theory, proposed by IBM researchers in the 1980s. The core idea is: at any given moment, only present users with the information and action options they need at their current stage, with advanced features hidden in deeper layers. This principle is extremely common in software design — think of Word's "More Options" collapsible menus, or iOS's layered settings structure. Agent Skills bring this design philosophy into AI engineering, letting the model normally perceive only the "title and summary" of skills — like seeing only dish names on a menu, not the complete recipe for each dish. In real-world engineering at scale, Skills clearly have the advantage.

Hands-On Setup: Complete Workflow Based on OpenCode

Since native Claude Code has certain usage restrictions, this hands-on tutorial uses its open-source alternative OpenCode (official site opencode.ai) for demonstration. OpenCode is an open-source terminal AI coding assistant. Unlike Claude Code, which requires an Anthropic subscription, OpenCode supports connecting to APIs from multiple model providers, including OpenAI, Anthropic, Zhipu AI, DeepSeek, and more, giving users greater flexibility and cost control. It runs in a command-line environment and can directly access the local file system and execute shell commands, making it a natural foundation for agent-like operations. Its Skills mechanism draws inspiration from Claude Code's .claude/commands and CLAUDE.md designs, but further enhances openness and extensibility.

Environment Setup

First, you need to install Node.js. Node.js is a JavaScript runtime environment built on Chrome's V8 engine. It enables JavaScript to run in server-side and command-line environments and serves as the foundational runtime for modern frontend toolchains and numerous CLI tools. The installation process is straightforward — just follow the prompts — and once complete, verify with the node -v command to confirm the version number outputs correctly.

Next, go to the OpenCode official website and choose the installation method for your system: the base command is for Mac, while Windows users use the corresponding command (provided Node.js is already installed). Copy and run the command to complete installation, then type opencode to launch the development tool.

Configuring Models

After launching, there are several useful commands to note. Type /models to view available models. If no API has been configured, there's usually only one somewhat unstable free model.

To connect a more stable model (such as Zhipu GLM-4.7), type /connect, search for "Zhipu AI," press Enter, and fill in the API Key obtained from the official platform (create a new one if you don't have one). Zhipu AI is a leading Chinese AI company whose GLM series models excel at Chinese language understanding and code generation, with relatively affordable API pricing, making them suitable as a primary model for development and debugging. After successful configuration, the corresponding model will be highlighted.

Verifying Local File Operation Capabilities

Once configured, first test OpenCode's local file operation capabilities. For example, ask it to "write a modern poem about AI and save it to a .txt file," and it will complete the write operation directly in the current path. This demonstrates the key difference between OpenCode and ordinary chat tools — it can directly operate on the local directory. This capability stems from OpenCode's execution within a terminal environment: it has the current user's file system permissions and can create, read, modify, and delete files by executing shell commands. This is a capability that purely web-based chat tools lack, and it's the foundational prerequisite for agent-like operations.

Loading the Official Skills Library: Teaching the Model to Read PDFs

Reproducing the Model's Limitations

First, reproduce the pain point mentioned earlier: place a PDF in the current directory and ask OpenCode to read "the content of page 6." As expected, it responds with "Unable to read PDF file, please convert it to text format." This is a textbook example of a bare model's inability to read external files.

Introducing the Anthropic Official Skills Library

The solution is to use the skills library officially provided by Anthropic. Anthropic is the company behind the Claude series of models, founded by former OpenAI Research VP Dario Amodei, and is a global leader in AI safety and large language models. Their official skills library is a pre-built skill collection designed specifically for agent-like workflows. Go to their GitHub repository, find the skills source code, and download the archive directly. These official skills cover various scenarios including PDF operations, PPT processing, theme factories, web apps, and more.

The configuration steps are as follows:

1. Copy the official skill files;
2. Navigate to the user configuration directory config/opencode;
3. If there's no skills folder, create one manually;
4. Paste the skill files into it;
5. Restart OpenCode for the configuration to take effect.

Verifying the Results

After restarting, ask "What skills are currently available," and the model will correctly read all the skills that were just loaded. Note that at this point, the model only "knows" the names and descriptions of these skills — it hasn't loaded their specific execution logic. This is the progressive disclosure principle in action.

Now ask it again to "use skills to read page 6 of the document," and you can see it proactively invoking the corresponding skill — not only reading the description from the skill but also executing the built-in Python script. These Python scripts typically rely on PDF parsing libraries like PyPDF2 or pdfplumber, which can decode PDF binary structures, extract plain text content, and return it to the context in a format the model can understand.

After the script runs successfully, the model accurately reports that "the document has 121 pages" and extracts the content from page 6 about "the development history of model algorithms." Manual verification confirms the extracted content is accurate. This is the deep-level capability loading effect that Agent Skills deliver — the model's capability boundary expands from "can only process text" to "can orchestrate external tools to process data in any format."

Two Configuration Modes and Engineering Value

Skills support two configuration approaches:

• Global configuration: Universal across all projects, with skill files stored in the user-level configuration directory. Ideal for high-utility foundational skills like file format conversion and general data processing;
• Project-level configuration: Only effective within a specific project directory, with skill files stored in the project root's configuration folder. Ideal for project-specific skills like code generation standards for a particular framework or project-specific deployment workflows.

This layered configuration design is similar to Git's .gitconfig (global) and .gitattributes (project-level), allowing developers to flexibly manage skill collections at different levels of granularity.

With Agent Skills, OpenCode gains more powerful local execution capabilities — batch document processing, folder organization, and automated task execution all become possible. By loading the official skills library, AI achieves a capability leap in scenarios like document processing, content creation, and data analysis.

More importantly, this paradigm evolves AI from simple conversation to a truly engineering-grade execution model. Compared to MCP's full-scale protocol approach, embracing Agent Skills means lower costs, higher efficiency, and stronger scalability — which is exactly the key to building scalable intelligent AI workflows. As the open-source community continues to contribute more high-quality skill templates, Agent Skills are poised to become an indispensable infrastructure layer in the engineering deployment of AI.

Key Takeaways