Agent Skills

What it is

@bestblogs/skills is a bundle of SKILL.md files that package BestBlogs' core capabilities into agent-invocable skills.

Designed for:

• Claude Code (~/.claude/skills/)
• Codex (~/.codex/skills/)
• Cursor / OpenClaw / custom agents — anything that can shell out to a CLI

Relationship to OpenAPI and CLI

Layer	Form	For whom
OpenAPI	Direct REST	Any language, server-side integrations
CLI	Shell commands	Humans, scripts, CI
Skills (this page)	SKILL.md + trigger phrases	Agents (auto-triggered)

Skills shell out to the CLI underneath and consume --json output. No new protocol, no MCP dependency — any agent that can run shell commands works.

The 5 skills (25 primitives)

Skill	When it triggers	Key primitives
bestblogs-profile	Cold start / view interest profile	intake setup, intake show
bestblogs-discover	Today / for-you / following / trending / search / newsletter	today, for-you, following, trending, search, newsletter list/get
bestblogs-read	Deep-read a single piece (meta + markdown + report read back)	read deep (orchestration primitive)
bestblogs-capture	Bookmark / highlight / note / reading history	12 primitives across bookmark, highlight, note, history
bestblogs-explain	Explain why something was recommended / source contribution / score	explain profile, explain contribution, explain score

Cross-skill shared contract

Every discover / brief candidate returns a Candidate Explain block:

Field	Meaning
candidateSource	Which recall channel this came from (public brief / your follows / interest profile / exploratory fallback)
selectionReason	One-line "why we picked this for you"
fallbackApplied	Whether a fallback channel was used because personalized recall came up short
personalized	Whether the item was re-ranked by your profile (always false for public streams)

Agents must surface these fields when showing candidates — so users can always ask "why this one?"

Install

Prerequisite: install the CLI

npm install -g @bestblogs/cli
bestblogs auth login

One-shot install into Claude Code + Codex

npx @bestblogs/skills install

This symlinks all 5 SKILL.md files into:

• ~/.claude/skills/ (Claude Code)
• ~/.codex/skills/ (Codex)

Codex's built-in .system and gstack directories are detected and skipped — never overwritten.

Install into just one

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

List installed skills

npx @bestblogs/skills list

From source

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

How to use after installing

Restart your agent client; from there, just ask in natural language using the trigger phrases described in each SKILL.md:

• "What's worth reading on BestBlogs today?" → triggers bestblogs-discover today
• "Deep read this RAW_xxx for me" → triggers bestblogs-read deep
• "Bookmark this and add a note" → triggers bestblogs-capture bookmark add + note add
• "Why did BestBlogs recommend this to me?" → triggers bestblogs-explain score

Use with other agent ecosystems

Skills are MCP-free. Any client that can shell out to a CLI can use them — treat the primitives in each SKILL.md as a tool schema:

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

Releases & versioning

• npm package: @bestblogs/skills
• Versioned independently from the CLI, with tags like skills-vX.Y.Z
• Full SKILL.md files and primitive lists in the GitHub README