Skills & slash commands

The Beakr CLI ships with a Claude Code skill and pre-built slash commands that teach your AI assistant how to use the knowledge base effectively.

Beakr skill

The beakr skill activates automatically when you ask Claude about your organization, team, projects, or decisions. It teaches Claude when and how to use each MCP tool without you needing to specify which tool to call.

The skill uses progressive disclosure -- Claude loads the core decision tree first, then reads detailed reference docs only when it needs them:

Reference	Loaded when
Core skill (SKILL.md)	Always -- tool selection, scoping, citation rules, proactive capture
Research workflow	User asks a broad research question
Writing pages	User wants to create or update a KB page
Auditing	User wants to check KB quality
Provenance	User asks where information came from

What the skill knows

Which tool to use for each type of question (research vs search vs browse)
How to scope queries to projects or personal knowledge
How to cite sources and present provenance stances
Page type conventions (topic, person, decision, meeting, etc.)
Content formatting rules (section markers, cross-references, Related Pages)
How to interpret provenance stances (supports, contradicts, qualifies)
When the conversation produces durable information worth capturing — see below

Proactive capture

The skill instructs the agent that Beakr is the team's organizational memory and that it shares responsibility for keeping it useful. When the conversation produces a durable, shareable, not-already-captured piece of information — a decision with rationale, a named process, an ownership assignment, a dated event, a key external relationship — the agent surfaces a brief suggestion before writing:

This decision about X seems worth capturing — want me to propose it for your wiki?

The agent never auto-writes. Every write goes through the proposal flow: you see what would be added, with section IDs, inline citations, and event dates, and explicitly accept or dismiss it.

Captures when…	Skips when…
Information would still matter in 6 months	Debugging traces or transient state
Others on the team would benefit	Already in source code, git history, or Linear/Jira
`kb_search` confirms it's not already there	Hot takes, speculation, "thinking out loud"
You can write to the target scope (your project, your personal space)	The user clearly considers it ephemeral

Slash commands

In addition to the automatic skill, four slash commands are available for specific workflows. Type / in Claude Code to see them.

/kb-research

Deep research across your entire knowledge base. Searches multiple spaces in parallel, reads top pages, traces provenance, follows the knowledge graph, and synthesizes findings by theme with citations.

/kb-research What decisions were made about the API redesign?

/kb-search

Fast, targeted search. Searches all spaces in parallel, reads the top hits, follows links, and presents synthesized answers with page citations -- not just raw search results.

/kb-search authentication flow

/kb-write

Create or update a knowledge base page. Checks for duplicates, finds the right parent, chooses the correct page type, writes with proper section markers and cross-references, and verifies the result.

/kb-write A page about our authentication architecture

/kb-audit

Audit knowledge base quality. Checks the graph for orphans and dead ends, spots structural issues, samples content quality, verifies provenance, and reports findings by severity with fix recommendations.

/kb-audit
/kb-audit focus on the engineering space

Installation

The skill and all four slash commands are installed automatically by beakr setup (see Installation). They land in:

~/.claude/skills/beakr/        # the Beakr skill
~/.claude/commands/kb-*.md     # /kb-search, /kb-research, /kb-write, /kb-audit
~/.codex/skills/beakr/         # same skill for Codex

To install them into the current project instead (committed, shared with teammates):

beakr setup --scope project

This writes to ./.claude/skills/beakr/ and ./.claude/commands/ in the current working directory.

Custom commands

You can create your own slash commands by adding markdown files to .claude/commands/ in your project. Each file becomes a /filename command. Use $ARGUMENTS as a placeholder for user input.