Agent Skills Practical Guide for Beginners

Introduction

The concept of Agent Skills has been trending in the AI engineering community for a while now. As the projects I've worked on grew increasingly complex, my understanding of it went through an evolution that can be described as "seeing a mountain as a mountain → seeing a mountain not as a mountain → seeing a mountain as a mountain again."

Many people assume Skills is just about writing a few prompt templates for AI. But if you dig into the underlying implementation, you'll find that it actually addresses one of the trickiest problems in Agentic AI: dynamic context management.

This article walks through my cognitive evolution, breaks down what Agent Skills really is, what pain points it solves, and uses OpenCode as an example to dissect its implementation at the code level.

Three Stages of Understanding: What Exactly is Skills?

Stage One: A Simple Protocol Layer

Initially, I thought Skills was just a simple protocol or specification. Like MCP (Model Context Protocol), Skills seemed to be just minor engineering optimizations—wrapping prompts to look nicer and organizing them neatly into a unified folder. I didn't think it was anything novel, just "old wine in a new bottle."

Stage Two: A Variant of Workflow

Later, I began to think Skills was essentially the "intent recognition" node in a workflow. In traditional workflows, you need intent recognition (Router) to decide which branch to jump to, thereby loading different prompts. I thought at the time: "Oh, isn't Skills just moving this branching logic inside the conversation?" In other words, I believed Skills was just a reskinned intent recognition node.

Stage Three: Dynamic Capability Injection

Finally, I realized my previous understandings were too narrow. Intent recognition is typically external, explicit routing logic; Skills is a core capability of Agentic AI. It's not simple "branching"—it's a progressive loading mechanism. It allows the Agent, without knowing what problems it might encounter in the future, to proactively go to the "bookshelf" and pick up a specific "manual" to read based on the current context.

What Engineering Pain Points Does Skills Solve?

If the goal is just to make AI do things, why not simply make the System Prompt longer? Why introduce Skills? The core reasons boil down to three issues:

1. Cost and Context Limitations: As capabilities grow, if you stuff all tool prompts into the System Prompt, the Context Window will blow up instantly, and token costs will rise exponentially.

2. Attention Dilution: Making AI search for a simple instruction among tens of thousands of irrelevant tool descriptions drastically reduces its instruction-following capability—it gets lost in thousands of tokens that have nothing to do with the task. Skills implements "load on demand," keeping the context concise and focused.

3. Distribution and Reuse: Through standardized definitions, Skills becomes a portable "skill package." This provides the foundation for community distribution (similar to what npm is to Node.js).

Standardized Definition: What Does a Skill Look Like?

Current mainstream implementations (like the Claude Code style) typically use a file directory structure to define a Skill. A typical .claude/skills or .opencode/skills directory structure looks like this:

skill.md (required): Core description file containing prompts and usage instructions.
scripts/ (optional): Specific execution scripts (Python/Bash).
assets/ (optional): Static resource files.

This is a "documentation as code" design philosophy.

Code Deep Dive: How Skills Are Loaded

This is the highlight of this article. Many articles only discuss concepts—let's look directly at the code implementation. Since Claude Code is not open source, we'll use the open-source project OpenCode's logic as an example to trace the full journey of a Skill from definition to being invoked by AI.

1. Defining the Skill

Let's say we define a release tool in .opencode/skills/git-release/SKILL.md:

---
name: git-release
description: Create consistent releases and changelogs
metadata:
  audience: maintainers
---

## What I do
- Draft release notes from merged PRs
- Propose a version bump

## When to use me
Use this when you are preparing a tagged release.

2. Registration and Discovery

At system startup, the full content of SKILL.md (i.e., the detailed prompt under "What I do") is NOT fed to the LLM. The system only reads the metadata from the Frontmatter and builds a concise XML list injected into the System Prompt:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

Key point: At this stage, the LLM knows the skill exists but doesn't know how to use it in detail. This saves a tremendous amount of tokens.

3. Activation and Injection

When the user asks, "Help me release a new version," the LLM, based on the descriptions in the System Prompt, determines that this skill is needed. It doesn't directly execute git commands—it first outputs a special Tool Call:

{
    tools: "skill({ name: 'git-release' })"
}

4. The Runtime Loop

Only after the system captures this request does it read the full content of SKILL.md and append it to the current Context.

Here's a pseudocode implementation of the core logic:

context = system_prompt + available_skills_summary 

while True:
    # 1. LLM thinks
    llm_output = LLM(context)

    # 2. Check if done
    if llm_output.type == "final":
        return llm_output.content

    # 3. Handle tool calls
    elif llm_output.type == "tool_call":
        tool_name = llm_output.name
        
        # Core logic: distinguish between "loading a skill" and "executing an action"
        if tool_name == "skill":
             # 【Key step】Dynamic loading: read the MD file content
             skill_name = llm_output.args['name']
             skill_content = read_file(f".skills/{skill_name}/SKILL.md")
             
             # Inject the skill details as an "observation result" or "new rules" into context
             result = f"[System: Skill '{skill_name}' loaded.]\n{skill_content}"
        
        else:
             # Execute a regular tool (e.g., run a shell command)
             result = run_actual_tool(tool_name, llm_output.args)

        # Append the result to the conversation history and enter the next loop iteration
        context += format_observation(result)

Through this loop, in the next interaction round, the LLM's Context now contains the detailed prompt guidance for git-release, enabling it to accurately execute the release task.

Conclusion

The essence of Agent Skills is leveraging the LLM's planning capability to achieve on-demand context swapping.

It's not just a code-level optimization—it's a shift in architectural paradigm: from "preparing everything for AI" to "teaching AI how to acquire the capabilities it needs." Understanding this, you'll also understand the inevitable path Agentic AI must take as it scales in complexity.