Phase 4 / Ep 17: Understanding Skill Architecture — SKILL.md is the Soul

🎯 Learning Objective: Gain a deep understanding of Skill definition specifications and operating mechanisms.

1. What is a Skill?

A Skill is OpenClaw's capability declaration unit. It is not an executable program, but a set of instructions and metadata injected into the Agent's context, telling the AI "what you can do and how to do it".

2. Skill File Structure

graph TD
    subgraph Skill["📦 A Complete Skill"]
        SkillMD["SKILL.md\nMetadata + Instructions\n(YAML frontmatter + Markdown)"]
        Scripts["scripts/ (Optional)\nHelper Scripts"]
        Examples["examples/ (Optional)\nExample Usage"]
        Resources["resources/ (Optional)\nTemplates · Data Files"]
    end

    SkillMD -->|"Injected per conversation"| Context["Agent Context Window"]
    Scripts -->|"Agent Invocation"| Exec["Tool Execution"]

3. SKILL.md Format Specification

name: weather-query
description: Enables the Agent to query weather information for global cities
version: 1.0.0
author: your-username
tags: [weather, utility, api]
permissions: [network]

# Weather Query Skill

## Usage Scenarios
Use this skill when the user asks weather-related questions.

## Operating Steps
1. Parse the city name mentioned by the user
2. Call scripts/query_weather.sh to get weather data
3. Return results in a friendly format

## Output Format
- City Name
- Current Temperature
- Weather Conditions
- 3-day Forecast

## Limitations
- Only supports cities in China and the United States
- Maximum 60 queries per hour

YAML Frontmatter Fields

4. Skill Operating Mechanism

sequenceDiagram
    participant Boot as Boot Phase
    participant Agent as Agent
    participant Skill as SKILL.md
    participant LLM as LLM

    Boot->>Agent: Load all Skills
    Agent->>Skill: Read SKILL.md content
    Agent->>Agent: Inject Skill instructions into context

    Note over Agent: User sends message
    Agent->>LLM: Prompt contains Skill instructions
    LLM->>Agent: "Should use weather-query"
    Agent->>Agent: Execute scripts/query_weather.sh
    Agent->>LLM: Submit execution results

⚠️ Token Cost: The text of each Skill is injected into the context, consuming Tokens. Do not install unnecessary Skills!

Next Episode Preview: Ep 18, a tour of the 10 essential Skills to install—core skills like web-search, file-manager, git-assist, and more.