跳转到主要内容
Logo

Agent Skills

@bestblogs/skills — 给 Claude Code / Codex / Cursor 等智能体的 SKILL.md 套件，主动触发 BestBlogs 能力。

它是什么

@bestblogs/skills 是一组 SKILL.md 文件，把 BestBlogs 的核心能力打包成 智能体可主动触发 的技能。

适用于：

  • Claude Code（~/.claude/skills/）
  • Codex（~/.codex/skills/）
  • Cursor / OpenClaw / 自研 agent —— 任何能 shell out 到 CLI 的客户端

与 OpenAPI / CLI 的关系

层 形态 谁来用
OpenAPI 直接调 REST 任何编程语言、服务端集成
CLI 命令行命令 人类、脚本、CI
Skills（本页） SKILL.md + 触发词 智能体（自动主动触发）

Skills 底层 shell out 到 CLI，再消费 --json 输出。所以 skills 不引入新协议，也不依赖 MCP——任何能跑 shell 命令的 agent 客户端都能用。

当前 5 个 Skills（25 个原语）

Skill 何时触发 关键原语
bestblogs-profile 冷启动 / 查看兴趣画像 intake setup、intake show
bestblogs-discover 今日 / 个性化 / 关注流 / 热趋 / 搜索 / 周刊 today、for-you、following、trending、search、newsletter list/get
bestblogs-read 深读一条内容（meta + markdown + 回传 read 行为） read deep（编排级原语）
bestblogs-capture 收藏 / 划线 / 笔记 / 阅读历史 bookmark add/list/remove、highlight add/list、note add/list、history list/clear 等 12 项
bestblogs-explain 解释推荐理由 / 来源贡献 / 评分细节 explain profile、explain contribution、explain score

跨 skill 共享契约

所有 discover / brief 类返回的候选都带一组 Candidate Explain 字段：

字段 含义
candidateSource 这条候选来自哪个召回通道（公共早报 / 你的关注 / 兴趣画像 / 探索性兜底）
selectionReason 一句话解释「为什么把它选给你」
fallbackApplied 个性化召回不足时是否触发了兜底
personalized 是否经过你的画像重排（公共流为 false）

智能体在向用户展示候选时 必须透传这些字段，方便用户随时质疑「为什么是这条」。

安装

前置：先装 CLI

npm install -g @bestblogs/cli
bestblogs auth login

一键安装到 Claude Code + Codex

npx @bestblogs/skills install

默认会把 5 个 SKILL.md 软链到：

  • ~/.claude/skills/（Claude Code）
  • ~/.codex/skills/（Codex）

Codex 自带的 .system 与 gstack 目录会被自动跳过，不会覆盖。

只装到其中之一

npx @bestblogs/skills install --client claude
npx @bestblogs/skills install --client codex

列出已安装

npx @bestblogs/skills list

从源码安装

git clone https://github.com/ginobefun/bestblogs-monorepo.git
cd bestblogs-monorepo/bestblogs-skills
./install.sh

安装后怎么用

重启 agent 客户端后，按 SKILL.md 的 description 描述的触发词自然提问即可，agent 会主动调用对应 skill：

  • 「今天 BestBlogs 有什么值得读？」 → 触发 bestblogs-discover today
  • 「帮我深读这篇 RAW_xxx」 → 触发 bestblogs-read deep
  • 「收藏这条 + 加一段笔记」 → 触发 bestblogs-capture bookmark add + note add
  • 「为什么 BestBlogs 推这条给我？」 → 触发 bestblogs-explain score

给其他 agent 生态用

Skills 不依赖 MCP。任何能 shell out 到 CLI 的客户端都能直接用——把 SKILL.md 里的「原语清单」当工具 schema 即可，例如：

tool_schema:
  name: bestblogs_discover_today
  invocation: bestblogs discover today --limit 20 --json
  output_schema: ../bestblogs-cli/src/api/types.ts#CandidateExplainSchema

发布与版本

← 回到文档首页