本期介绍

当前主流LLM应用开发框架越来越多，如LangChain、Dify、LlamaIndex、Semantic Kernel、Coze 等，效果更是每过几天就会给人一个大惊喜！

这些主流框架，复杂度也越来越高，刚入门的同学很多云里雾里，无从下手，本🤖 simple_skills_agent极简项目基于最原生的Python，不使用任何开发框架，以天气Agent的极简项目，为大家展现出Agent skills的开发框架的核心逻辑和设计理念，重点突出 Agent Skills 新范式，将特定领域知识，用结构化的文档层次组织，通过LLM决策过程中基于渐进式的动态加载，来最低消耗资源（Tokens），按需激活上下文工程，来引导LLM给出在特定领域 基于经验（skills) "干好活”！！

1. 什么是Agent Skills

1.1 Agent Skills 场景

我们先看 2 个 Agent Skills 的相关视频，来感性了解一下相关的场景：

【引用声明-来自公众号：轩辕的编程宇宙。在此感谢作者！】

【引用声明-来自小红书：阿甘探AI。在此感谢作者！】

Agent和MCP解决AI "能不能干活“ 的问题，也就是AI能做什么决策，能自主调用哪些工具去干活。
而 Agent Skills解决的是AI "能不能把活干好“ 的问题，它最大的亮点是决策的 “渐进式披露”，从业务Skills规则和流程，保证结果的稳定输出。

1.2 Agent Skills发展历史回顾

2022 年 OpenAI 发布 GPT-3.5 并支持函数调用，为 Agent Skills 奠定技术基础；
2023 年 LangChain、LlamaIndex 等主流 Agent 框架发布，提出 “Tool/Chain/Agent” 分层模型，将 Skill 封装为 Chain/Tool 组合，是 Agent Skills 的工程化雏形；
2024 年至今，“技能可扩展” 成为 Agent 框架核心设计原则，出现配置化 Skill 开发（如通过 Markdown/JSON 定义 Skill，无需改动核心代码），也是当前新手开发的主流方向。

Agent Skills 的发展与 AI Agent、大语言模型（LLM）的技术演进深度绑定，核心经历了 3 个阶段，从 “硬编码函数” 逐步进化为 “LLM 驱动的可扩展技能”，也是新手需要理解的技术演进逻辑：

阶段	时间	核心特征	技术基础	局限性
1. 硬编码函数阶段	2020 年前（LLM 普及前）	Agent 能力为硬编码的函数 / 模块，无 “Skill” 概念，能力固定，需手动编写所有逻辑	传统规则引擎、专家系统、强化学习	扩展性极差，新增能力需大幅修改核心代码；无自然语言理解能力，仅支持指令式调用
2. 函数调用（Function Call）阶段	2022-2023 年（GPT-3.5/4 发布后）	LLM 支持调用外部函数 / 工具，首次实现 “思考 → 调用执行” 的解耦，开始出现 “Skill” 的雏形（函数封装为简单技能）	LLM 函数调用能力、API 标准化	Skill 仅为 “函数的简单包装”，无统一的 Skill 定义和管理；缺乏意图与 Skill 的智能匹配，参数解析需硬编码；无法组合多个 Skill 完成复杂任务
3. 标准化 Agent Skills 阶段	2023 年至今（AI Agent 框架爆发期）	提出标准化 Skill 概念，将 Skill 设计为独立、可管理、可组合的能力单元；支持 LLM 驱动的意图匹配、参数解析、Skill 组合；出现专门的 Skill 管理框架 / 模块	大模型进阶理解能力、Prompt 工程、微服务架构、配置化开发	行业暂无统一的 Skill 标准；复杂任务的 Skill 组合逻辑仍需优化；部分框架的 Skill 与核心代码耦合度较高

1.3 Agent Skills的价值

Agent工程扩展LLM能力传统上主要有如下几个方案：

提示词工程（Prompt Engineering）：通过给LLM输入指定的文本来引导LLM给出结果；
工具调用（Tool Calling）：通过LLM决策相关的外阅API，把模型与工具相连接，完成某项任务；
微调（Fine-tuning）：通过重新训练LLM权重来内化增强能力。

Agent Skills 代表了一种新的范式，上下文工程（Context Engineering)，将特定领域知识，用结构化的文档层次组织，通过LLM决策过程中基于渐进式的动态加载，来最低消耗资源（Tokens），按需激活上下文工程，来引导LLM给出在特定领域 基于经验（skills) "干好活”！

2 🤖 simple\_skills\_agent项目介绍

2.1 项目介绍

本次实战项目"🤖simple\_skills\_agent"，是一个高度解耦、纯本地 LLM 驱动的天气查询 Agent 框架，核心特点是「规则与代码分离」（所有业务规则都在weather\_skill.md中）、「LLM 主导决策」（参数解析 / 结果生成全由本地 llama-3-8b 完成）、「无硬编码逻辑」（修改规则仅需改 md 文件）。

本项目的基本流程为：加载技能定义 → 命令行接收用户输入 → 大模型意图识别（确认是否为天气查询） → 技能执行（提取城市 → 调用天气工具 → 获取数据） → 大模型润色结果 → 命令行输出回复。

详细流程图如下：

这个项目能充分展现当前工业界流行的 Skills 模式，核心流程和技术点一一对应，且无框架依赖，让大家对底层逻辑有一个最基本的认知，遵循 Agent 技能开发的标准执行链路：

技能加载：Agent 启动时加载skills目录的技能定义文件，解耦配置与代码；
用户输入接收：命令行作为交互入口，模拟 Agent 的用户交互层；
意图识别：由大模型（llama-3-8b）判断用户输入是否触发对应技能，是 Skills 的核心前置判断（避免无意义的工具调用）；
技能执行：触发技能后，执行该技能的专属逻辑（提取参数 → 调用工具 → 获取原始数据）；
结果整合 / 润色：大模型对工具返回的结构化原始数据进行自然语言润色，符合人类对话习惯；
结果输出：将最终结果返回给用户，完成一次技能调用。

2.2 🤖 simple\_skills\_agent项目整体架构

2.2.1 架构设计

类型：轻量级纯 Python Agent 框架（无第三方 Agent 框架依赖，原生实现）；
部署方式：本地离线部署（依赖 LM Studio 运行 llama-3-8b，无外网 LLM API 调用）；
核心思想：Skills 驱动（所有业务规则通过weather\_skill.md定义，代码仅负责执行）；
交互方式：命令行交互（CLI），适合本地调试和基础功能验证。

2.2.2 关键模块

🤖 simple\_skills\_agent项目，有如下几个核心模块，职责说明如下表:

层级	核心模块	职责
基础配置层	全局变量（LM Studio / 路径）	定义环境参数（模型地址、Skill 路径、LLM 推理参数）
Skill 加载层	load\_weather\_skill()	解析 md 格式的 Skill 规则，转换为结构化字典
LLM 调用层	call\_lm\_studio()	封装 LM Studio 的 OpenAI 兼容 API 调用，为上层提供统一的 LLM 调用接口
指令解析层	parse\_user\_query()	调用 LLM 解析用户自然语言，提取结构化参数（城市 / 查询时间）
工具调用层	WeatherTool 类	按 Skill 规则调用气象局 API，获取并过滤天气数据
结果生成层	generate\_answer()	调用 LLM 将结构化天气数据转为口语化自然语言
交互层	main()函数	命令行交互循环，串联所有模块完成端到端流程

2.2.3 基本代码流程

项目代码simple\_skills\_agent.py的基本处理流程如下：

| | | |
| - | - | - |

main函数项目启动 -> 加载skills规则 -> 初始化天气类 -> 循环响应用户问题（接受用户输入 -> 解析用户指令 -> 调用工具 -> LLM格式化返回用户的答案。

2.2.4 基本代码框架

项目代码simple\_skills\_agent.py的基本框架如下：

Python
import os
import re
import json
import requests
from typing import Dict, Any

# 全局配置（适配本机LM Studio，保留你的原有配置）
# LM Studio开启OpenAI兼容API后的基础地址（默认端口1234，无需修改）
LM_STUDIO_BASE_URL = "http://localhost:1234/v1"
# 本机部署的模型名称（需和LM Studio中显示的模型名一致）
LM_STUDIO_MODEL = "llama-3-8b"
# 大模型请求参数（适配llama-3-8b，温度0.0保证解析稳定）
LLM_CONFIG = {
"temperature": 0.0, # 纯规则解析，温度设为0，结果更稳定
"max_tokens": 512,
"top_p": 0.9,
"stream": False
}
# Skills目录路径（固定为项目下的skills目录）
SKILLS_DIR = os.path.join(os.path.dirname(__file__), "skills")
# 优化后的天气Skill文件路径（对应你优化后的skills.md，重命名为weather_skill.md）
WEATHER_SKILL_FILE = os.path.join(SKILLS_DIR, "weather_skill.md")

# 第一步：Skill加载模块（适配优化后的skills.md结构）
def load_weather_skill() -> Dict[str, Any]:
"""
从优化后的weather_skill.md加载结构化的天气Skill规则
返回结构化字典，而非纯文本，便于后续模块调用（解耦更彻底）
:return: 结构化Skill字典，包含所有规则信息
"""
# 解析优化后的skills.md，提取所有结构化信息
skill_dict = {
"raw_content": skill_content, # 保留原始内容，供LLM解析使用
"description": "",
"tool": {
"name": "",
"type": "",
"url": "",
"param_mapping": "",
"timestamp_rule": "",
"headers_rule": ""
},
"core_fields": [],
"llm_instruction": ""
}

return skill_dict

# 本地大模型调用模块（保留你的原有逻辑）
def call_lm_studio(prompt: str) -> str:
"""
调用本机LM Studio的llama-3-8b模型，返回模型生成的文本
基于LM Studio的OpenAI兼容API，无框架依赖
:param prompt: 大模型的提示词/指令
:return: 模型生成的纯文本结果
"""
# 构造OpenAI兼容的请求体
payload = {
...
}
# 解析大模型返回结果
result = response.json()
return result

#第三步：指令解析模块（适配优化后的解析规则）
def parse_user_query(user_input: str, skill_dict: Dict[str, Any]) -> Dict[str, Any]:
"""
调用本地LLM，根据优化后的Skill规则解析用户指令
严格遵循skills.md中的解析要求，无硬编码规则
:param user_input: 用户原始命令行输入
:param skill_dict: 结构化的天气Skill字典
:return: 结构化参数字典，如{"city": "上海", "query_time": "now"}
"""
# 构造解析提示词（严格按优化后的Skill规则）
prompt = f"""
你是一个严格遵守规则的AI Agent指令解析器，必须按以下规则解析用户的天气查询指令：
"""
# 第四步：调用本地LLM获取解析结果
parse_result = call_lm_studio(prompt)
...

#  第四步：工具调用模块（完全基于Skill规则，无硬编码）
class WeatherTool:
"""
天气工具类，完全按优化后的weather_skill.md规则实现
所有工具逻辑（API地址、参数、请求头）均从Skill读取，无硬编码
"""
def __init__(self, skill_dict: Dict[str, Any]):
# 从Skill字典中提取API地址（核心：无硬编码）
self.weather_api = skill_dict["tool"]["url"]
# 从Skill中提取核心查询项（用于结果过滤）
self.core_fields = skill_dict["core_fields"]
...

# 第五步：行动-技能执行：提取城市→调用天气工具→获取数据
def get_weather_data(self, city_name: str) -> Dict[str, Any]:
"""
获取指定城市的原始天气数据，严格按Skill的核心查询项过滤
:param city_name: 解析后的城市名
:return: 结构化天气数据字典（匹配核心查询项）
"""
response = self.session.get(api_url, timeout=10, verify=False)
# 5. 按Skill的核心查询项构造结果（无硬编码字段）
weather_result = {
"城市": city_name,
f"{self.core_fields[0]}(℃)": real_time.get("temperature", "暂无数据"),
f"{self.core_fields[1]}": daily.get("dayText", "暂无数据"),
f"{self.core_fields[2]}": real_time.get("windDirection", "暂无数据"),
f"{self.core_fields[3]}": real_time.get("windSpeed", "暂无数据"),
f"{self.core_fields[4]}(%)": real_time.get("humidity", "暂无数据")
}
return weather_result


# 第七步：结果生成模块（LLM主导，无硬编码生成规则）
def generate_answer(weather_data: Dict[str, Any], skill_dict: Dict[str, Any]) -> str:
"""
调用本地LLM，将结构化天气数据转为自然语言回答
生成规则完全由LLM主导，无硬编码的文本拼接
:param weather_data: 工具返回的结构化天气数据
:param skill_dict: 结构化的天气Skill字典
:return: 口语化自然语言回答
"""
# 构造生成提示词（LLM主导结果格式化）
prompt = f"""
你是一个友好的天气查询助手，需要将以下结构化天气数据转为口语化的自然语言回答：
"""
# 第八步：调用本地LLM生成结果
return call_lm_studio(prompt)

# 第六步：核心Agent主逻辑+命令行交互（保留你的原有交互体验）
def main():
"""Agent主入口，实现：Skill加载→命令行交互→指令解析→工具调用→结果生成→响应"""
print("=" * 60)
print("🤖【原生Python Skills Agent - 天气查询助手（纯LLM驱动）】")
print("提示：1. 输入城市天气查询问题（如：今天上海的天气如何？）；2. 输入exit/退出可终止程序；3. 仅支持国内城市")
print("=" * 60 + "\n")

try:
# 初始化：加载结构化天气Skill（仅加载一次）
print("🔧 正在加载天气Skill规则...")
skill_dict = load_weather_skill()
print(f"✅ 成功加载天气Skill：{WEATHER_SKILL_FILE}\n")

# 初始化天气工具（完全基于Skill规则）
weather_tool = WeatherTool(skill_dict)

# 命令行持续交互循环
while True:
# 第二步：获取用户输入
user_input = input("🙋 你：").strip()
# 核心Agent执行流程
try:
# 1. 解析用户指令，提取结构化参数
print("🤖 Agent：正在解析你的查询指令...")
parse_data = parse_user_query(user_input, skill_dict)

city = parse_data["city"]
print(f"✅ Agent：解析成功，目标查询城市：{city}")

# 2. 调用天气工具，获取结构化天气数据
print("🌤️ Agent：正在调用天气工具查询数据...")
weather_data = weather_tool.get_weather_data(city)

# 3. 第九步：调用LLM，生成自然语言回答
print("📝 Agent：正在整理查询结果...")
answer = generate_answer(weather_data, skill_dict)

# 4. 第十步：调用天气工具，获取结构化天气数据输出最终结果
print(f"\n🤖 Agent：{answer}\n")

# 程序入口
if __name__ == "__main__":
main()

3. 🤖 simple\_skills\_agent代码详解

以下分别按照🤖 simple\_skills\_agent项目的主体结构，分别详细代码介绍：

3.1 项目依赖&基础配置（全局变量）

Python
# LM Studio配置（本地大模型核心）
LM_STUDIO_BASE_URL = "http://localhost:1234/v1" # OpenAI兼容API地址
LM_STUDIO_MODEL = "llama-3-8b" # 本地加载的模型名
LLM_CONFIG = {
"temperature": 0.0, # 0温度=无随机性，保证解析结果稳定
"max_tokens": 512, # 限制生成长度，避免冗余
"top_p": 0.9,
"stream": False
}
# Skill路径配置（解耦核心）
SKILLS_DIR = os.path.join(os.path.dirname(__file__), "skills")
WEATHER_SKILL_FILE = os.path.join(SKILLS_DIR, "weather_skill.md")

核心作用：集中管理环境参数，修改时无需改动业务代码；
设计亮点：temperature=0.0是纯规则解析场景的最优配置（避免 LLM 生成随机结果）；
关键细节：os.path.dirname(file)保证路径适配不同运行环境（相对路径 → 绝对路径）。

3.2 Skill 加载层（load\_weather\_skill()）

Python
def load_weather_skill() -> Dict[str, Any]:
# 1. 文件存在性校验
if not os.path.exists(WEATHER_SKILL_FILE):
raise FileNotFoundError(...)
# 2. 读取md文件
with open(...) as f:
skill_content = f.read()
# 3. 结构化解析（正则提取各模块）
skill_dict = {
"raw_content": skill_content, # 保留原始内容供LLM使用
"description": "", # 技能描述
"tool": {...}, # 工具配置（API地址/参数）
"core_fields": [], # 核心查询项
"llm_instruction": "" # LLM解析规则
}
# 4. 正则提取各字段（适配md格式）
desc_match = re.search(r'## 技能描述\n(.*?)\n## 绑定工具', skill_content, re.DOTALL)
# ... 其他正则提取逻辑
return skill_dict

核心作用：将非结构化的 md 文件转为结构化字典，让代码可直接读取规则；
设计亮点：
保留raw\_content字段，避免重复读取文件；
正则使用re.DOTALL（.匹配换行），适配 md 的多行文本；
提取核心字段时去除序号 / 括号（如实时气温（℃）→实时气温）；
关键细节：所有解析逻辑基于 md 的固定格式，修改 md 结构时需同步调整正则。

3.3 LLM 调用层（call\_lm\_studio()）

Python
def call_lm_studio(prompt: str) -> str:
# 1. 构造OpenAI兼容请求体
payload = {
"model": LM_STUDIO_MODEL,
"messages": [{"role": "user", "content": prompt}],
**LLM_CONFIG
}
# 2. 发送POST请求
response = requests.post(
url=f"{LM_STUDIO_BASE_URL}/chat/completions",
headers={"Content-Type": "application/json"},
json=payload,
timeout=60 # 本地模型推理慢，超时设60秒
)
response.raise_for_status() # 主动抛出HTTP异常
# 3. 解析结果
result = response.json()
return result["choices"][0]["message"]["content"].strip()

核心作用：封装 LLM 调用逻辑，为上层提供统一的「提示词 → 生成文本」接口；
设计亮点：
完全兼容 OpenAI 的 API 格式，适配 LM Studio 的默认配置；
timeout=60适配本地模型推理速度（避免过早超时）；
response.raise\_for\_status()主动抛出异常，便于上层捕获；
关键细节：无 API 密钥配置（LM Studio 本地调用无需密钥），符合离线部署需求。

3.4 指令解析层（parse\_user\_query()）

Python
def parse_user_query(user_input: str, skill_dict: Dict[str, Any]) -> Dict[str, Any]:
# 1. 构造严格的提示词（核心：规则驱动）
prompt = f"""
你是一个严格遵守规则的AI Agent指令解析器...
【核心解析规则】
{skill_dict['llm_instruction']}
【用户原始指令】：{user_input}
【强制要求】：仅返回JSON格式...
"""
# 2. 调用LLM
parse_result = call_lm_studio(prompt)
# 3. 清洗结果（去除llama-3-8b可能输出的```标记）
parse_result = re.sub(r"```(json)?|```", "", parse_result).strip()
# 4. JSON解析容错
try:
return json.loads(parse_result)
except json.JSONDecodeError:
return {"error": "..."}

核心作用：实现「自然语言 → 结构化参数」的转换，纯 LLM 驱动无硬编码解析逻辑；
设计亮点：
提示词强制要求「仅返回 JSON」，避免 LLM 生成冗余文本；
结果清洗逻辑适配 llama-3-8b 的输出习惯（模型可能带代码块标记）；
JSON 解析容错，保证程序不崩溃；
关键细节：所有解析规则都来自skill\_dict，修改规则仅需改 md 文件。

3.5 工具调用层（WeatherTool类）

Python
class WeatherTool:
def __init__(self, skill_dict: Dict[str, Any]):
self.weather_api = skill_dict["tool"]["url"] # 从Skill读取API地址
self.core_fields = skill_dict["core_fields"] # 从Skill读取核心字段
self.session = requests.Session() # 会话复用提升效率
# 模拟浏览器请求头，避免API风控
self.session.headers.update({...})

def get_weather_data(self, city_name: str) -> Dict[str, Any]:
# 1. 构造API地址（时间戳+城市名替换）
timestamp = str(int(time.time()))
api_url = self.weather_api.replace("{city_name}", city_name).replace("{timestamp}", timestamp)
# 2. 发起请求
response = self.session.get(api_url, timeout=10, verify=False)
response.raise_for_status()
# 3. 解析数据并按核心字段过滤
raw_data = response.json()
weather_result = {
"城市": city_name,
f"{self.core_fields[0]}(℃)": real_time.get("temperature", "暂无数据"),
# ... 其他字段
}
return weather_result

核心作用：按 Skill 规则调用外部 API，获取结构化天气数据；
设计亮点：
完全无硬编码：API 地址、核心字段均从 Skill 读取；
requests.Session()复用 TCP 连接，提升多次请求效率；
verify=False适配气象局 API 的 SSL 证书问题；
缺失值统一返回「暂无数据」，提升用户体验；
关键细节：API 参数替换（{city\_name}/{timestamp}）严格按 Skill 规则实现。

3.6 结果生成层（generate\_answer()）

Python
def generate_answer(weather_data: Dict[str, Any], skill_dict: Dict[str, Any]) -> str:
prompt = f"""
你是一个友好的天气查询助手...
【核心要求】
1. 仅包含{skill_dict['core_fields']}这5项信息；
2. 缺失数据显示「暂无数据」；
3. 回答口语化、简洁易懂；
【结构化天气数据】：
{json.dumps(weather_data, ensure_ascii=False, indent=2)}
"""
return call_lm_studio(prompt)

核心作用：实现「结构化数据 → 自然语言」的转换，纯 LLM 驱动无硬编码文本拼接；
设计亮点：
提示词明确约束输出规则（仅包含核心字段、口语化）；
json.dumps(ensure\_ascii=False)保证中文正常显示；
完全由 LLM 处理格式，无需手动拼接字符串；
关键细节：提示词的「友好助手」角色设定，让生成结果更符合用户预期。

3.7 交互层（main()函数）

Python
def main():
# 1. 初始化（加载Skill+创建工具实例）
skill_dict = load_weather_skill()
weather_tool = WeatherTool(skill_dict)
# 2. 交互循环
while True:
user_input = input("🙋 你：").strip()
# 退出/空输入处理
if user_input in ["exit", "退出", "q", "Q"]: break
if not user_input: continue
# 3. 核心流程
parse_data = parse_user_query(user_input, skill_dict)
if "error" in parse_data:
print(f"❌ Agent：{parse_data['error']}\n")
continue
weather_data = weather_tool.get_weather_data(parse_data["city"])
answer = generate_answer(weather_data, skill_dict)
print(f"\n🤖 Agent：{answer}\n")

核心作用：串联所有模块，提供用户交互入口；
设计亮点：
异常捕获机制（try/except）保证程序不崩溃；
清晰的状态提示（🔧/✅/🌤️/📝）提升用户体验；
仅加载一次 Skill / 工具实例，提升运行效率；
关键细节：交互循环的「退出条件」和「空输入处理」，避免无效执行。

4. 🤖 simple\_skills\_agent运行效果

项目运行步骤

步骤 1：启动 LM Studio 本地大模型 API

打开 LM Studio→「Server」→ 选择 llama-3-8b→点击「Start Server」，确保控制台显示Server running on http://127.0.0.1:1234。

步骤 2：

将代码保存为simple\_weather\_agent.py，命令行进入文件所在目录，执行：

python simple_skills_agent.py

或直接在VS2026 IDE环境中点执行

步骤 3：运行成功后，弹出对话界面：

5. 🤖simple\_skills\_agent项目的源码

项目源代码：simple_skills_agent

6. 总结

Agent Skills 开发的关键技术小结，所有技术点均为当前 Agent Skills 开发的核心技术，且用 Python 原生实现，无框架封装，方便你理解底层：

技能定义解耦：技能的工具选择、查询项、执行规则全部写在weather\_skill.md，修改技能无需改核心代码（比如想换成百度天气，仅需修改 md 文件和少量工具调用代码）；
大模型驱动的意图识别：放弃传统的正则硬匹配，由大模型基于技能定义做意图判断，泛化性更强（比如用户问 “上海今天热吗？”“成都现在刮什么风？” 都能识别为天气查询）；
工具调用封装：将天气接口调用封装为独立的call\_weather\_tool函数，符合 Skills 的工具化思想（一个技能对应一个 / 多个工具，工具与 Agent 核心逻辑解耦）；
本地大模型原生对接：兼容 OpenAI API 格式，用 Python 内置的http.client实现请求，无任何第三方库依赖，理解大模型 API 的底层通信逻辑；
参数提取与结构化处理：从用户输入中提取核心参数（城市名），工具返回结构化数据，再由大模型转为自然语言，体现 Agent 的 “感知 - 执行 - 表达” 能力；
技能的单一职责：weather\_skill仅负责天气查询，后续扩展其他技能（如快递查询、时间查询），仅需在skills目录添加新的 md 文件，再在代码中添加对应技能执行逻辑，符合 Skills 的模块化开发思想。