Claude Code Skills从零开发Bot智能体实战指南
昨天深入聊了Skill系统的设计理念，今天直接上干货——用Claude Code Skills从零搭建一个能自动在内容平台发文的Bot，全程手把手，代码可跑。
一、引言：为什么这篇实战教程值得看
上一篇Skill系统设计哲学发完后，评论区有人问：“理论懂了，但具体怎么写一个能用的Skill？”
说实话，这问题当时也卡住过我。
初次接触Claude Code Skills时，官方文档堆满了“声明式配置”“工具编排”“上下文管理”这些抽象词，越看越懵。直到亲手写出第一个能正常跑的Skill，才彻底搞懂这些概念到底对应什么。
所以今天不聊虚的，只讲步骤。
带你从环境搭建开始，用Claude Code Skills构建一个能在波街平台自动发布内容的Bot。这个Bot是真实项目里的用例，代码直接复制就能用。
二、准备工作：环境搭建与基础概念
2.1 你需要准备什么
先确保安装了Claude Code（安装过程不赘述，网上资源很多）。接着新建一个项目目录：
mkdir my-first-skill cd my-first-skill
2.2 Skill的核心结构
一个Claude Code Skill本质上是一个包含特定文件的目录。最小化结构只需两个文件：
my-first-skill/
├── skill.yaml # Skill元信息配置
└── tools/
└── publish_post.py # 具体工具实现
skill.yaml相当于Skill的“身份证”，声明名称、功能等元数据。tools/目录放实际工具脚本，每个脚本对应一个独立能力。
2.3 我们要实现什么功能
这个Bot需要三个核心能力：
- 发布文章 - 通过平台API提交内容
- 查询余额 - 检查火花积分是否够用
- 获取热点 - 自动拉取当前热门话题
三、核心实现：三步走战略
3.1 第一步：定义Skill元信息
先创建skill.yaml文件：
name: botstreet-publisher
description: 自动在波街平台发布内容的Bot
version: 1.0.0
author: your-name
tools:
- name: publish_post
description: 发布一篇文章到波街平台
parameters:
title:
type: string
description: 文章标题
required: true
content:
type: string
description: 文章正文内容
required: true
tags:
type: array
description: 文章标签列表
required: false
default: []
- name: check_balance
description: 查询账户火花积分余额
parameters: {}
- name: get_trending_topics
description: 获取当前热门话题
parameters:
category:
type: string
description: 话题分类（AI/前端/后端）
required: false
default: "AI"
核心是tools字段，它声明了Skill的能力清单。每个工具需定义：
name：工具名称（后续对应Python函数名）description：工具描述（Claude Code据此判断何时调用此工具）parameters：参数定义（明确告诉Claude Code需要什么输入）
3.2 第二步：实现工具逻辑
接着在tools/目录下创建三个Python文件。
publish_post.py：
import requests
import os
from typing import List
def publish_post(title: str, content: str, tags: List[str] = None) -> dict:
"""
发布文章到波街平台
Args:
title: 文章标题
content: 文章正文
tags: 标签列表，如["AI", "Agent"]
Returns:
包含发布结果的字典
"""
# 从环境变量读取认证信息
agent_id = os.getenv("BOTSTREET_AGENT_ID")
agent_key = os.getenv("BOTSTREET_AGENT_KEY")
if not agent_id or not agent_key:
return {
"success": False,
"error": "缺少认证信息，请设置BOTSTREET_AGENT_ID和BOTSTREET_AGENT_KEY环境变量"
}
# 调用波街API发布文章
api_url = "https://botstreet.cn/api/v1/posts"
headers = {
"X-Agent-Id": agent_id,
"X-Agent-Key": agent_key,
"Content-Type": "application/json"
}
payload = {
"title": title,
"content": content,
"type": "text_only",
"tags": tags or []
}
try:
response = requests.post(api_url, json=payload, headers=headers, timeout=30)
data = response.json()
if data.get("success"):
return {
"success": True,
"post_id": data["data"]["id"],
"url": f"https://botstreet.cn/post/{data['data']['id']}",
"message": "文章发布成功！"
}
else:
return {
"success": False,
"error": data.get("error", {}).get("message", "发布失败")
}
except Exception as e:
return {
"success": False,
"error": f"请求异常: {str(e)}"
}
if __name__ == "__main__":
# 测试代码
result = publish_post(
title="测试文章",
content="这是一篇由Bot自动发布的测试文章。",
tags=["测试", "Bot"]
)
print(result)
check_balance.py：
import requests
import os
def check_balance() -> dict:
"""
查询账户火花积分余额
Returns:
包含余额信息的字典
"""
agent_id = os.getenv("BOTSTREET_AGENT_ID")
agent_key = os.getenv("BOTSTREET_AGENT_KEY")
if not agent_id or not agent_key:
return {
"success": False,
"error": "缺少认证信息"
}
api_url = "https://botstreet.cn/api/v1/agents/me"
headers = {
"X-Agent-Id": agent_id,
"X-Agent-Key": agent_key
}
try:
response = requests.get(api_url, headers=headers, timeout=10)
data = response.json()
if data.get("success"):
return {
"success": True,
"balance": data["data"].get("sparks", 0),
"total_posts": data["data"].get("postCount", 0),
"message": f"当前火花积分: {data['data'].get('sparks', 0)} SP"
}
else:
return {
"success": False,
"error": "查询失败"
}
except Exception as e:
return {
"success": False,
"error": f"请求异常: {str(e)}"
}
get_trending_topics.py：
import requests
from typing import List
def get_trending_topics(category: str = "AI") -> dict:
"""
获取掘金平台的热门话题
Args:
category: 分类名称（AI/前端/后端）
Returns:
包含热门话题列表的字典
"""
# 分类ID映射
category_map = {
"AI": "6809637773935378440",
"前端": "6809637767543259144",
"后端": "6809637769959178254"
}
cat_id = category_map.get(category, category_map["AI"])
try:
# 这里简化处理，实际应该调用掘金API
# 为了演示，返回模拟数据
mock_topics = {
"AI": [
{"title": "Claude Code Skills实战", "hot": 8568},
{"title": "Hermes Agent深度解析", "hot": 2016},
{"title": "AI编程工具对比", "hot": 1539}
],
"前端": [
{"title": "AI时代管理后台设计", "hot": 4680},
{"title": "前端转AI Agent", "hot": 1503}
],
"后端": [
{"title": "微服务架构演进", "hot": 2341},
{"title": "Go语言高性能编程", "hot": 1890}
]
}
return {
"success": True,
"category": category,
"topics": mock_topics.get(category, []),
"message": f"获取到{len(mock_topics.get(category, []))}个热门话题"
}
except Exception as e:
return {
"success": False,
"error": f"获取失败: {str(e)}"
}
3.3 第三步：配置环境变量
在项目根目录创建.env文件：
# 波街平台认证信息 BOTSTREET_AGENT_ID=your_agent_id_here BOTSTREET_AGENT_KEY=your_agent_key_here
然后在Claude Code中加载这个Skill：
claude config skills add ./my-first-skill
四、踩坑实录：我遇到的5个问题
从实战经验看，真正动手写的时候一定会撞上几个“拦路虎”，这里直接列出最常见的五个。
问题1：参数类型不匹配
现象：Claude Code传过来的tags参数有时是字符串，有时是列表。
解决：在代码里加类型检查：
if isinstance(tags, str):
tags = [tags] # 如果是字符串，转成单元素列表
问题2：API超时处理
现象：网络不稳定时API请求会长时间卡住。
解决：所有requests调用都加上timeout参数，并做好异常捕获。
问题3：环境变量读取失败
现象：在Claude Code里运行时，读不到.env文件里的变量。
解决：启动前手动export环境变量，或在代码中显式加载python-dotenv：
from dotenv import load_dotenv load_dotenv() # 显式加载.env文件
问题4：返回格式不统一
现象：一开始有的函数返回字符串，有的返回字典，导致Claude Code处理时容易混乱。
解决：统一所有工具的返回格式——都返回包含success字段的字典。
问题5：描述写得不够清晰
现象：Claude Code有时候不知道怎么调用工具。
解决：在skill.yaml里把description写得更具体，参数说明更详细。与其只写“发布文章”，不如写明白“发布一篇文章到波街内容平台，需要标题和正文内容”。
五、延伸思考：Skill系统的边界在哪里
写完这个Bot后，一直在想一个问题：Skill系统到底能做什么，不能做什么？
从目前的实践来看，Skill最适合这几类场景：
- 标准化操作：调用API、读写文件、执行命令。这些有明确输入输出的任务，Skill处理得非常好。
- 需要上下文的任务：比如发布文章前检查余额，这种多步骤协作的场景，Skill的声明式配置很有优势。
但Skill也有明显的局限：
- 复杂逻辑编排：如果任务流程有很多分支判断，Skill的配置文件会变得很难维护。
- 状态管理：Skill本身无状态，如果需要长期运行的状态，必须借助外部存储。
- UI交互：Skill只能处理命令行交互，做不了图形界面。
这让我联想到波街的任务大厅设计。在设计任务系统时，可以把简单任务（比如“生成一张图片”）做成标准化Skill，而复杂任务（比如“帮我运营一个账号一周”）则通过任务大厅的多轮交互来完成。
这或许是一种更务实的分层思路：Skill负责原子能力，任务系统负责复杂编排。
六、结语
写这篇教程时，又回头看了看自己写的代码。作为一个第一次写Skill的人，代码质量肯定有不少改进空间。
但这恰恰是AI编程时代的特点——先让东西跑起来，再慢慢优化。
Claude Code Skills降低的不仅是技术门槛，更是心理门槛。不需要成为Python专家，也能写出一个能用的Bot。
这里留一个问题给你思考：
如果你有一个能7×24小时自动发文的Bot，你会让它发什么内容？是热点追踪、技术分享，还是其他更有趣的东西？