Complete Guide to Agent Skills: Core Concepts, Design Patterns, and Hands‑On Code

Agent Skills Open Standard

Agent Skills is an open standard that structures prompts into three progressive layers: Metadata , Instruction and Resource . Only the Metadata layer is loaded into the model context by default; the Instruction and Resource layers are loaded on demand, which reduces token consumption compared with loading a full prompt.

Claude Code Installation and Configuration

Install Node.js 18 (or newer) and Git.

Install Claude Code globally: npm install -g @anthropic-ai/claude-code Create a settings.json file (e.g. under C:\Users\{username}\.claude) with the authentication token and base URL for the model provider, for example:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your‑api‑key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}

Create a .claude.json file in the same directory to mark onboarding completion:

{
  "hasCompletedOnboarding": true
}

Start Claude Code with the claude command. The first time a directory is used, the CLI asks whether the directory should be trusted; answer YES to proceed.

Creating a Skill

A Skill is a folder under .claude/skills/your‑skill. The folder must contain a file named SKILL.md. The file starts with a YAML front‑matter block that defines the skill’s metadata, for example:

---
name: srt字幕转markdown笔记
description: 把srt字幕文件转换为markdown笔记
---

After the front‑matter, the Instruction layer is written in Markdown and describes the exact task. In the example, the instruction asks the model to convert an SRT subtitle file into a Markdown note with strict punctuation, paragraph structure and optional screenshot placeholders.

Resource Layer

The Resource layer can hold auxiliary files. The example creates three subfolders inside the skill directory: scripts, references and assets. A Python script screenshot.py placed in scripts parses custom markers of the form Screenshot‑[hh:mm:ss], invokes ffmpeg to capture a frame from a video, and replaces the marker with an image link.

import argparse, json, logging, os, re, subprocess
from pathlib import Path
from typing import List, Tuple

def extract_screenshot_markers(markdown: str) -> List[Tuple[str, int]]:
    pattern = r"(?:\*?)Screenshot-(?:\[(\d{2}):(\d{2}):(\d{2})\]|(\d{2}):(\d{2}):(\d{2}))"
    results = []
    for match in re.finditer(pattern, markdown):
        hh = match.group(1) or match.group(4)
        mm = match.group(2) or match.group(5)
        ss = match.group(3) or match.group(6)
        total_seconds = int(mm) * 60 + int(ss)
        results.append((match.group(0), total_seconds))
    return results

During execution, Claude Code first loads only the Metadata layer, recognises that the dropped file is an .srt subtitle, and prompts the user whether to invoke the corresponding Skill. After confirmation, the Instruction layer is loaded, the model generates Markdown containing screenshot markers, and the screenshot.py script is run to replace those markers with real image links. This demonstrates the progressive‑disclosure mechanism.

Skill vs. Model Context Protocol (MCP)

Focus : Skills organise prompts and load them progressively; MCP standardises external tool/service integration.

Analogy : Skills are a catalog‑driven instruction manual; MCP is a standardised toolbox.

Token consumption : Skills consume low tokens because only metadata is loaded initially; MCP incurs higher token usage as tool descriptions and call logic are part of the prompt.

Core artifact : Skills are defined by a Markdown file ( SKILL.md); MCP is implemented as a software package or service.

Implementation difficulty : Skills are easy to create (file‑level configuration); MCP requires protocol compliance and often server‑side development.

Advanced Skill Usage

To extend the subtitle‑to‑markdown skill, the Resource layer can be organised as follows:

Create subfolders scripts, references and assets inside the skill directory to separate executable code, documentation and static assets.

Place the executable Python script screenshot.py in scripts. The script extracts markers such as Screenshot‑[00:03:12], calls ffmpeg to capture a frame from the associated video, stores the image under an output directory, and rewrites the Markdown to embed the image link.

Update the Instruction layer to invoke the script after the initial Markdown is produced, e.g. by adding a step:

7. **后续处理**:
   markdown生成完毕以后，调用
   python scripts/screenshot.py
   对视频进行截图，执行python脚本时不需要传递任何参数

The full screenshot.py script (including argument parsing, logging, screenshot generation and Markdown replacement) is provided in the source and can be run directly by Claude Code without being sent to the model as part of the prompt.

Running the Skill End‑to‑End

Place the target .srt subtitle file (and optionally the corresponding .mp4 video) in the project root.

Execute claude and drag the .srt file onto the CLI.

Claude Code loads only the Metadata layer, detects the subtitle, and asks whether to use the defined Skill.

After confirming, the Instruction layer is loaded; the model generates a Markdown note with Screenshot‑[hh:mm:ss] placeholders.

Claude Code then runs python scripts/screenshot.py. The script processes the placeholders, captures screenshots from the video (if present), and replaces the placeholders with actual image links.

The final output is a Markdown file that contains formatted text and embedded screenshots, and the token cost is limited to the metadata and the on‑demand instruction, illustrating the token‑saving advantage of progressive disclosure.

Key Takeaways

Agent Skills provide a lightweight, prompt‑driven mechanism for extending model capabilities while keeping token usage low.

The three‑layer design (Metadata → Instruction → Resource) enables on‑demand loading of detailed logic and auxiliary assets.

Claude Code demonstrates a concrete workflow: install, configure, define a skill with SKILL.md, organise resources, and execute the skill with progressive loading.

Compared with MCP, Skills are easier to author (file‑level configuration) and are best suited for scenarios where the primary cost is prompt length rather than frequent external tool calls.

Skills and MCP are complementary; MCP can expose complex tools while Skills can orchestrate their usage through structured prompts.