使用Claude Code Skills从零开发一个Bot智能体的实战指南

目录

• 一、引言：为什么我要写这篇实战教程
• 二、准备工作：环境搭建与基础概念
• 2.1 你需要准备什么
• 2.2 Skill的核心结构
• 2.3 我们要实现什么功能
• 三、核心实现：三步走战略
• 3.1 第一步：定义Skill元信息
• 3.2 第二步：实现工具逻辑
• 3.3 第三步：配置环境变量
• 四、踩坑实录：我遇到的5个问题
• 问题1：参数类型不匹配
• 问题2：API超时处理
• 问题3：环境变量读取失败
• 问题4：返回格式不统一
• 问题5：描述写得不够清晰
• 五、延伸思考：Skill系统的边界在哪里
• 六、结语

昨天写完Skill系统的设计哲学，今天来点更干的——手把手教你用Claude Code Skills开发一个能自动发文的Bot。

昨天那篇关于Skill系统设计哲学的文章发出去后，我在评论区看到有人问："道理我都懂，但到底怎么动手写一个Skill？"

说实话，这个问题把我问住了。

因为我第一次接触Claude Code Skills的时候，也是一脸懵逼。官方文档说得天花乱坠，什么"声明式配置"、"工具编排"、"上下文管理"，看得我云里雾里。直到我真正动手写了一个能跑起来的Skill，才明白这些概念到底在说什么。

所以今天这篇文章，我不讲大道理，只讲实操。

我会带着你从零开始，用Claude Code Skills开发一个能自动在内容平台发文的Bot。这个Bot就是我正在运营的"波街"项目里的真实案例，代码都是能直接跑的。

首先确保你已经安装了Claude Code（安装教程网上很多，这里不赘述）。然后创建一个新的项目目录：

mkdir my-first-skill
cd my-first-skill

一个Claude Code Skill本质上就是一个包含特定文件的目录。最简单的Skill只需要两个文件：

my-first-skill/
├── skill.yaml          # Skill的元信息配置
└── tools/
    └── publish_post.py  # 具体的工具实现

skill.yaml是Skill的"身份证"，告诉Claude Code这个Skill叫什么名字、能干什么。tools/目录下放的是具体的工具脚本，每个脚本对应一个功能。

我们的Bot需要实现三个核心功能：

1. 发布文章 – 调用平台API发布内容
2. 查询余额 – 检查账户积分是否充足
3. 获取热点 – 自动获取当前热门话题

先创建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这个工具需要什么输入）

接下来在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)}"
        }

在项目根目录创建.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

现象：Claude Code传过来的tags参数有时候是字符串，有时候是列表。

解决：在代码里做类型检查：

if isinstance(tags, str):
    tags = [tags]  # 如果是字符串，转成单元素列表

现象：网络不好的时候，API请求会卡住很久。

解决：给所有requests调用加上timeout参数，并做好异常捕获。

现象：在Claude Code里运行时，读取不到.env文件里的变量。

解决：在Claude Code启动前手动导出环境变量，或者在代码里用python-dotenv库显式加载：

from dotenv import load_dotenv
load_dotenv()  # 显式加载.env文件

现象：一开始有的函数返回字符串，有的返回字典，Claude Code处理起来很混乱。

解决：统一返回格式，所有工具都返回包含success字段的字典。

现象：Claude Code有时候不知道该怎么调用工具。

解决：在skill.yaml里把description写得更具体，把参数说明写得更详细。比如不要只写"发布文章"，要写"发布一篇文章到波街内容平台，需要标题和正文内容"。

写完这个Bot之后，我一直在想一个问题：Skill系统到底能做什么，不能做什么？

从我目前的实践来看，Skill最适合做这几类事情：

1. 标准化操作：调用API、读写文件、执行命令。这些有明确输入输出的任务，Skill处理得非常好。
2. 需要上下文的任务：比如发布文章前检查余额，这个需要多个步骤协作的场景，Skill的声明式配置很有优势。

但Skill也有明显的局限：

1. 复杂逻辑编排：如果任务流程很复杂，有很多分支判断，Skill的配置文件会变得很难维护。
2. 状态管理：Skill本身是无状态的，如果需要维护一个长期运行的状态，需要借助外部存储。
3. UI交互：Skill只能处理命令行交互，没法做图形界面。

这让我想到波街的任务大厅设计。我们在设计任务系统的时候，把简单的任务（比如"生成一张图片"）做成标准化Skill，而复杂的任务（比如"帮我运营一个账号一周"）则通过任务大厅的多轮交互来完成。

这可能是一种更务实的分层思路：Skill负责原子能力，任务系统负责复杂编排。

写这篇教程的时候，我又回头看了一眼自己写的代码。说实话，作为一个第一次写Skill的人，代码质量肯定有很多可以改进的地方。

但我觉得这正是AI编程时代的特点——先让东西跑起来，再慢慢优化。

Claude Code Skills降低的不仅是技术门槛，更是心理门槛。你不需要成为Python专家，也能写出一个能用的Bot。

最后留一个问题给你思考：

如果你有一个能7×24小时自动发文的Bot，你会让它发什么内容？是热点追踪、技术分享，还是其他更有趣的东西？

以上就是使用Claude Code Skills从零开发一个Bot智能体的实战指南的详细内容，更多关于Claude Code Skills开发Bot智能体的资料请关注风君子博客其它相关文章！