For agents

The agent skill

A skill teaches your coding agent when to record a fable (after shipping a feature), what belongs in one (how it works, which files, where the data flows), and where it goes — a private fables/ folder in the repo, or your dashboard over MCP.

Install

Claude Code: save the document below as .claude/skills/brainfables/SKILL.md in your repo (or ~/.claude/skills/brainfables/SKILL.md for all projects). Other agents: paste it wherever standing instructions live.

---
name: brainfables
description: Record a BrainFables fable — an interactive explainer of how a feature in this codebase works — after implementing or materially changing a feature. Use when the user says "record a fable", "fable this", "update the fables", or when you finish building something a future reader will need explained.
---

# Recording fables

BrainFables (https://brainfables.com) keeps living, interactive explainers ("fables") of how the
things in this codebase work. You build features faster than humans absorb them; a fable
is how they keep up. Record one after implementing or materially changing a feature —
one fable per feature or subsystem, not per commit. If a fable already covers the
feature, revise it instead of creating a duplicate.

## The format

A fable is one Markdown file: YAML frontmatter (title, summary, tags, difficulty 1-5,
model), then CommonMark extended with declarative directives (:::aside, :::deeper,
:::steps, :::quiz, :::params, :::plot, :::chart, :::diagram, …). No raw HTML, no
scripts — content is data, not code.

Fetch the complete authoring guide before writing your first fable:
- MCP: the `get_fable_format` tool (no API key needed), or
- HTTP: https://brainfables.com/format.md

Always validate with the `check_fable` MCP tool (no API key needed) and iterate until
it returns ok before saving anywhere.

## What a good code fable covers

- What the feature does and how it actually works — explain, don't just inventory.
- Which files participate, and the role of each.
- Where the data comes from, what transforms it, where it ends up — a
  `:::diagram` of the flow usually beats three paragraphs.
- `:::deeper` panels for the parts a future reader will ask "but why?" about.
- An interactive element (`:::params` + `:::plot`/`:::chart`, `:::quiz`) only when it
  genuinely explains better than prose.
- In the frontmatter, list the key source files in `tags` or the summary so the fable
  is findable from the code.

## Where to record

**Local mode (fully private)** — if the repo has a `fables/` folder, or the user wants
fables kept off the cloud: write `fables/<slug>.fable.md` (kebab-case slug named after
the feature). Optionally a `fables/project.json` with `{ "name": "Project Name" }`.
The owner reads these at https://brainfables.com/dashboard by connecting the folder — the files
never leave their machine. Still validate with `check_fable` first.

**Cloud mode** — if the `brainfables` MCP server is configured with an API key:

1. `list_projects` — find the project for this codebase; `create_project` once if absent.
2. `list_fables` with that projectId — does a fable already cover this feature?
3. If yes: `get_fable` for its current source, then `update_fable` with the revision.
4. If no: `submit_fable` with the projectId.

Cloud fables land on the owner's dashboard as personal (only they can see them).
Publishing to the community feed is their call, on the web — never describe a
submission as "published".

For cloud recording, also connect the MCP server with an API key from your profile. Local mode needs no key — files stay on your machine and the dashboard reads them straight from disk.