# 第五章 Skills (技能加载)


`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`

>“本专栏基于开源项目 `learn-claude-code` 的官方文档。原文档非常硬核，为了方便像我一样的新手小白理解，我对文档进行了**逐行精读**，并加入了很多**中文注释、大白话解释和踩坑记录**。希望这套‘咀嚼版’教程能帮你推开 AI Agent 开发的大门。”


项目地址：[shareAI-lab/learn-claude-code: Bash is all you need - A nano Claude Code–like agent, built from 0 to 1](https://github.com/shareAI-lab/learn-claude-code)

>"用到什么知识, 临时加载什么知识" -- 通过 tool_result 注入, 不塞 system prompt。


## 一、问题-**System Prompt（系统提示词）臃肿与 Token 浪费**


你希望智能体遵循特定领域的工作流: git 约定、测试模式、代码审查清单。全塞进系统提示太浪费 -- 10 个技能, 每个 2000 token, 就是 20,000 token, 大部分跟当前任务毫无关系。

## 二、解决方案


```
System prompt (Layer 1 -- always present):
+--------------------------------------+
| You are a coding agent.              |
| Skills available:                    |
|   - git: Git workflow helpers        |  ~100 tokens/skill
|   - test: Testing best practices     |
+--------------------------------------+

When model calls load_skill("git"):
+--------------------------------------+
| tool_result (Layer 2 -- on demand):  |
| <skill name="git">                   |
|   Full git workflow instructions...  |  ~2000 tokens
|   Step 1: ...                        |
| </skill>                             |
+--------------------------------------+
```
第一层: 系统提示中放技能名称 (低成本)。第二层: tool_result 中按需放完整内容。

## 三、工作原理


1. 每个技能是一个目录, 包含 `SKILL.md` 文件和 YAML frontmatter。


```
skills/
  pdf/
    SKILL.md       # ---\n name: pdf\n description: Process PDF files\n ---\n ...
  code-review/
    SKILL.md       # ---\n name: code-review\n description: Review code\n ---\n ...
```
什么是YAML frontmatter?

是一种在文档顶部嵌入结构化元数据的标准格式，由三个短横线 `---` 包裹的 YAML 键值对组成。**技能加载**，Agent 通过读取 frontmatter 中的 `name` 和 `description` 快速判断何时加载该技能，无需加载完整内容；同时体现了**渐进式披露**，只在前几轮暴露轻量级元数据（~100 tokens），匹配后才加载完整指令。

```
---

name: mcp-builder

description: Build MCP (Model Context Protocol) servers that give Claude new capabilities. Use when user wants to create an MCP server, add tools to Claude, or integrate external services.

---
```

1. SkillLoader 递归扫描 `SKILL.md` 文件, 用目录名作为技能标识。


```
class SkillLoader:
&nbsp; &nbsp; def __init__(self, skills_dir: Path):
&nbsp; &nbsp; &nbsp; &nbsp; self.skills_dir = skills_dir
&nbsp; &nbsp; &nbsp; &nbsp; self.skills = {}
&nbsp; &nbsp; &nbsp; &nbsp; self._load_all()

&nbsp; &nbsp; def _load_all(self):
&nbsp; &nbsp; &nbsp; &nbsp; if not self.skills_dir.exists():
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return
&nbsp; &nbsp; &nbsp; &nbsp; for f in sorted(self.skills_dir.rglob("SKILL.md")): 
&nbsp; &nbsp; &nbsp; &nbsp; #.rglob()深入遍历所有子目录，把所有名字完全匹配"SKILL.md"的文件路径全部找出
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; text = f.read_text()
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; meta, body = self._parse_frontmatter(text)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; name = meta.get("name", f.parent.name)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; self.skills[name] = {"meta": meta, "body": body, "path": str(f)}

&nbsp; &nbsp; def _parse_frontmatter(self, text: str) -> tuple:
&nbsp; &nbsp; &nbsp; &nbsp; """Parse YAML frontmatter between --- delimiters."""
&nbsp; &nbsp; &nbsp; &nbsp; match = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.DOTALL) #启用re.DOTALL后：.匹配任意字符，包括换行符
&nbsp; &nbsp; &nbsp; &nbsp; if not match:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return {}, text
&nbsp; &nbsp; &nbsp; &nbsp; meta = {}
&nbsp; &nbsp; &nbsp; &nbsp; for line in match.group(1).strip().splitlines():
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; if ":" in line:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; key, val = line.split(":", 1)
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; meta[key.strip()] = val.strip()
&nbsp; &nbsp; &nbsp; &nbsp; return meta, match.group(2).strip() # match.group(2).strip()：清理后的技能主体内容
&nbsp; &nbsp; &nbsp; &nbsp; 
&nbsp; &nbsp; def get_descriptions(self) -> str:
&nbsp; &nbsp; &nbsp; &nbsp; """Layer 1: short descriptions for the system prompt."""
&nbsp; &nbsp; &nbsp; &nbsp; if not self.skills:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return "(no skills available)"
&nbsp; &nbsp; &nbsp; &nbsp; lines = []
&nbsp; &nbsp; &nbsp; &nbsp; for name, skill in self.skills.items():
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; desc = skill["meta"].get("description", "No description")
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; tags = skill["meta"].get("tags", "")
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; line = f" &nbsp;- {name}: {desc}"
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; if tags:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; line += f" [{tags}]"
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; lines.append(line)
&nbsp; &nbsp; &nbsp; &nbsp; return "\n".join(lines)
&nbsp; &nbsp; &nbsp; &nbsp; 
&nbsp; &nbsp; def get_content(self, name: str) -> str:
&nbsp; &nbsp; &nbsp; &nbsp; """Layer 2: full skill body returned in tool_result."""
&nbsp; &nbsp; &nbsp; &nbsp; skill = self.skills.get(name)
&nbsp; &nbsp; &nbsp; &nbsp; if not skill:
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
&nbsp; &nbsp; &nbsp; &nbsp; return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
```

1. 第一层写入系统提示。第二层不过是 dispatch map 中的又一个工具。


```
SYSTEM = f"""You are a coding agent at {WORKDIR}.
Skills available:
{SKILL_LOADER.get_descriptions()}"""  &nbsp;<-- 这就是第一层

TOOL_HANDLERS = {
    # ...base tools...
    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
}
```
`load_skill` 的作用本质上就是**让大模型去读特定的 Markdown 文档**，模型知道有哪些技能 (便宜), 需要时再加载完整内容 (贵)。

## 四、相对 s04 的变更


|组件|之前(s04)|之后(s05)|
|:-:|:-:|:-:|
|Tools|5 (基础 + task)|5 (基础 + load_skill)|
|系统提示|静态字符串|+ 技能描述列表|
|知识库|无|skills/*/SKILL.md 文件|
|注入方式|无|两层 (系统提示 + result)|

## 五、试一试


```
cd learn-claude-code
python agents/s05_skill_loading.py
```
试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):


1. `What skills are available?`

2. `Load the agent-builder skill and follow its instructions`

3. `I need to do a code review -- load the relevant skill first`

4. `Build an MCP server using the mcp-builder skill`


## 六、完整代码


```
#!/usr/bin/env python3
import os
import re
import subprocess
from pathlib import Path

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)

if os.getenv("ANTHROPIC_BASE_URL"):
    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)

WORKDIR = Path.cwd()
client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]
SKILLS_DIR = WORKDIR / "skills"


# -- SkillLoader: scan skills/<name>/SKILL.md with YAML frontmatter --
class SkillLoader:
    def __init__(self, skills_dir: Path):
        self.skills_dir = skills_dir
        self.skills = {}
        self._load_all()

    def _load_all(self):
        if not self.skills_dir.exists():
            return
        for f in sorted(self.skills_dir.rglob("SKILL.md")):
            text = f.read_text()
            meta, body = self._parse_frontmatter(text)
            name = meta.get("name", f.parent.name)
            self.skills[name] = {"meta": meta, "body": body, "path": str(f)}

    def _parse_frontmatter(self, text: str) -> tuple:
        """Parse YAML frontmatter between --- delimiters."""
        match = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.DOTALL)
        if not match:
            return {}, text
        meta = {}
        for line in match.group(1).strip().splitlines():
            if ":" in line:
                key, val = line.split(":", 1)
                meta[key.strip()] = val.strip()
        return meta, match.group(2).strip()

    def get_descriptions(self) -> str:
        """Layer 1: short descriptions for the system prompt."""
        if not self.skills:
            return "(no skills available)"
        lines = []
        for name, skill in self.skills.items():
            desc = skill["meta"].get("description", "No description")
            tags = skill["meta"].get("tags", "")
            line = f"  - {name}: {desc}"
            if tags:
                line += f" [{tags}]"
            lines.append(line)
        return "\n".join(lines)

    def get_content(self, name: str) -> str:
        """Layer 2: full skill body returned in tool_result."""
        skill = self.skills.get(name)
        if not skill:
            return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
        return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"


SKILL_LOADER = SkillLoader(SKILLS_DIR)

# Layer 1: skill metadata injected into system prompt
SYSTEM = f"""You are a coding agent at {WORKDIR}.
Use load_skill to access specialized knowledge before tackling unfamiliar topics.

Skills available:
{SKILL_LOADER.get_descriptions()}"""


# -- Tool implementations --
def safe_path(p: str) -> Path:
    path = (WORKDIR / p).resolve()
    if not path.is_relative_to(WORKDIR):
        raise ValueError(f"Path escapes workspace: {p}")
    return path

def run_bash(command: str) -> str:
    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
    if any(d in command for d in dangerous):
        return "Error: Dangerous command blocked"
    try:
        r = subprocess.run(command, shell=True, cwd=WORKDIR,
                           capture_output=True, text=True, timeout=120)
        out = (r.stdout + r.stderr).strip()
        return out[:50000] if out else "(no output)"
    except subprocess.TimeoutExpired:
        return "Error: Timeout (120s)"

def run_read(path: str, limit: int = None) -> str:
    try:
        lines = safe_path(path).read_text().splitlines()
        if limit and limit < len(lines):
            lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
        return "\n".join(lines)[:50000]
    except Exception as e:
        return f"Error: {e}"

def run_write(path: str, content: str) -> str:
    try:
        fp = safe_path(path)
        fp.parent.mkdir(parents=True, exist_ok=True)
        fp.write_text(content)
        return f"Wrote {len(content)} bytes"
    except Exception as e:
        return f"Error: {e}"

def run_edit(path: str, old_text: str, new_text: str) -> str:
    try:
        fp = safe_path(path)
        content = fp.read_text()
        if old_text not in content:
            return f"Error: Text not found in {path}"
        fp.write_text(content.replace(old_text, new_text, 1))
        return f"Edited {path}"
    except Exception as e:
        return f"Error: {e}"


TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
}

TOOLS = [
    {"name": "bash", "description": "Run a shell command.",
     "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
    {"name": "read_file", "description": "Read file contents.",
     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
    {"name": "write_file", "description": "Write content to file.",
     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
    {"name": "edit_file", "description": "Replace exact text in file.",
     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
    {"name": "load_skill", "description": "Load specialized knowledge by name.",
     "input_schema": {"type": "object", "properties": {"name": {"type": "string", "description": "Skill name to load"}}, "required": ["name"]}},
]


def agent_loop(messages: list):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM, messages=messages,
            tools=TOOLS, max_tokens=8000,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return
        results = []
        for block in response.content:
            if block.type == "tool_use":
                handler = TOOL_HANDLERS.get(block.name)
                try:
                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                except Exception as e:
                    output = f"Error: {e}"
                print(f"> {block.name}: {str(output)[:200]}")
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
        messages.append({"role": "user", "content": results})


if __name__ == "__main__":
    history = []
    while True:
        try:
            query = input("\033[36ms05 >> \033[0m")
        except (EOFError, KeyboardInterrupt):
            break
        if query.strip().lower() in ("q", "exit", ""):
            break
        history.append({"role": "user", "content": query})
        agent_loop(history)
        response_content = history[-1]["content"]
        if isinstance(response_content, list):
            for block in response_content:
                if hasattr(block, "text"):
                    print(block.text)
        print()
```

s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（5）Skills (技能加载)

本文介绍AI Agent的技能加载机制，解决系统提示词臃肿问题。通过两层设计：系统提示只保留技能名称（低成本），需要时通过tool_result按需加载完整内容。SkillLoader扫描skills目录下的SKILL.md文件，解析YAML元数据，实现渐进式知识披露，大幅节省token消耗。

编程语言

本文介绍AI Agent开发中的技能加载机制，通过分层设计解决系统提示词臃肿问题。第一层系统提示仅包含技能元数据（约100token），第二层按需通过tool_result加载完整技能内容（约2000token）。采用YAML frontmatter管理技能元数据，实现高效的知识检索与调用，显著降低token消耗。开源项目learn-claude-code展示了具体实现方法。

智能体

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文介绍AI Agent开发中的技能加载机制，通过分层设计解决系统提示词臃肿问题。第一层系统提示仅包含技能元数据（约100token），第二层按需通过tool_result加载完整技能内容（约2000token）。采用YAML frontmatter管理技能元数据，实现高效的知识检索与调用，显著降低token消耗。开源...

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（5）Skills (技能加载)-腾讯云开发者社区-腾讯云

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（5）Skills (技能加载)

【从零手写 ClaudeCode：learn-claude-code 项目实战笔记】（5）Skills (技能加载)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐